From 5d2262d7c3072f7da342f87990e96c560cb7846b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Tue, 14 Apr 2020 11:07:35 +0200
Subject: [PATCH] =?UTF-8?q?man:=20hostname(5)=20=E2=80=94=20add=20descript?=
 =?UTF-8?q?ion=20of=20methods=20and=20properties?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 man/org.freedesktop.hostname1.xml | 77 ++++++++++++++++++-------------
 1 file 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"/>
@@ -240,6 +208,51 @@ node /org/freedesktop/hostname1 {
     <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     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>