man: hostname(5) — add description of methods and properties

1 files changed, 45 insertions, 32 deletions

diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml
index f707b9080d..f6eb9f3545 100644
--- a/man/org.freedesktop.hostname1.xml
+++ b/man/org.freedesktop.hostname1.xml
@@ -89,38 +89,6 @@ node /org/freedesktop/hostname1 {
 };
     </programlisting>
 
-    <!--method SetDeployment is not documented!-->
-
-    <!--method SetLocation is not documented!-->
-
-    <!--method GetProductUUID is not documented!-->
-
-    <!--property Hostname is not documented!-->
-
-    <!--property StaticHostname is not documented!-->
-
-    <!--property PrettyHostname is not documented!-->
-
-    <!--property IconName is not documented!-->
-
-    <!--property Chassis is not documented!-->
-
-    <!--property Deployment is not documented!-->
-
-    <!--property Location is not documented!-->
-
-    <!--property KernelName is not documented!-->
-
-    <!--property KernelRelease is not documented!-->
-
-    <!--property KernelVersion is not documented!-->
-
-    <!--property OperatingSystemPrettyName is not documented!-->
-
-    <!--property OperatingSystemCPEName is not documented!-->
-
-    <!--property HomeURL is not documented!-->
-
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.hostname1"/>
@@ -241,6 +209,51 @@ node /org/freedesktop/hostname1 {
     for that. For more information on these files and syscalls see the respective man pages.</para>
 
     <refsect2>
+      <title>Methods and Properties</title>
+
+      <para><function>SetHostname()</function> sets the transient (dynamic) hostname which is exposed by the
+      <varname>Hostname</varname> property. If empty, the transient hostname is set to the static hostname.
+      </para>
+
+      <para><function>SetStaticHostname()</function> sets the static hostname which is exposed by the
+      <varname>StaticHostname</varname> property. If empty, the built-in default of
+      <literal>&FALLBACK_HOSTNAME;</literal> is used.</para>
+
+      <para><function>SetPrettyHostname()</function> sets the pretty hostname which is exposed by the
+      <varname>PrettyHostname</varname> property.</para>
+
+      <para><function>SetIconName()</function>, <function>SetChassis()</function>,
+      <function>SetDeployment()</function>, and <function>SetLocation()</function> set the properties
+      <varname>IconName</varname> (the name of the icon representing for the machine),
+      <varname>Chassis</varname> (the machine form factor), <varname>Deployment</varname> (the system
+      deployment environment), and <varname>Location</varname> (physical system location), respectively.
+      </para>
+
+      <para><varname>PrettyHostname</varname>, <varname>IconName</varname>, <varname>Chassis</varname>,
+      <varname>Deployment</varname>, and <varname>Location</varname> are stored in
+      <filename>/etc/machine-info</filename>. See
+      <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+      the semantics of those settings.</para>
+
+      <para><function>GetProductUUID()</function> returns the "product uuid" as exposed by the kernel based
+      on DMI information in <filename>/sys/class/dmi/id/product_uuid</filename>. Reading the file directly
+      requires root privileges, and this method allows access to unprivileged clients through the PolicyKit
+      framework.</para>
+
+      <para><varname>KernelName</varname>, <varname>KernelRelease</varname>, and
+      <varname>KernelVersion</varname> expose the kernel name (e.g. <literal>Linux</literal>), release
+      (e.g. <literal>5.0.0-11</literal>, and version (i.e. the build number, e.g. <literal>#11</literal>) as
+      reported by
+      <citerefentry project="man-pages"><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+      <varname>OperatingSystemPrettyName</varname>, <varname>OperatingSystemCPEName</varname>, and
+      <varname>HomeURL</varname> expose the <varname>PRETTY_NAME=</varname>, <varname>CPE_NAME=</varname> and
+      <varname>HOME_URL=</varname> fields from
+      <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
+      purpose of those properties is to allow remote clients to access this information over D-Bus. Local
+      clients can access the information directly.</para>
+    </refsect2>
+
+    <refsect2>
       <title>Security</title>
 
       <para>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit