From debf2ddd2880e020070a9108925c4e42a7295d7f Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Tue, 14 Apr 2020 10:28:50 +0200
Subject: [PATCH] man: reorder hostname1(5)

---
 man/org.freedesktop.hostname1.xml | 49 ++++++++++++++++++-------------
 1 file changed, 29 insertions(+), 20 deletions(-)

diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml
index c852bed6de9..f707b9080de 100644
--- a/man/org.freedesktop.hostname1.xml
+++ b/man/org.freedesktop.hostname1.xml
@@ -219,10 +219,6 @@ node /org/freedesktop/hostname1 {
     it could not be auto-detected. Set this property to the empty string to reenable the automatic detection of
     the chassis type from firmware information.</para>
 
-    <para>A client that wants to change the local hostname for DHCP/mDNS should invoke
-    <code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via
-    <code>SetHostname("")</code>.</para>
-
     <para>Note that <filename>systemd-hostnamed</filename> starts only on request and terminates after a
     short idle period. This effectively means that <function>PropertyChanged</function> messages are not sent
     out for changes made directly on the files (as in: administrator edits the files with vi). This is
@@ -244,33 +240,46 @@ 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>
 
-    <para>The <varname>user_interaction</varname> boolean parameters can be used to control whether PolicyKit
-    should interactively ask the user for authentication credentials if required.</para>
+    <refsect2>
+      <title>Security</title>
+
+      <para>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit
+      should interactively ask the user for authentication credentials if required.</para>
+
+      <para>The PolicyKit action for <function>SetHostname()</function> is
+      <interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For
+      <function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is
+      <interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For
+      <function>SetIconName()</function> and <function>SetChassis()</function> it is
+      <interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para>
+    </refsect2>
+  </refsect1>
 
-    <para>The PolicyKit action for <function>SetHostname()</function> is
-    <interfacename>org.freedesktop.hostname1.set-hostname</interfacename>. For
-    <function>SetStaticHostname()</function> and <function>SetPrettyHostname()</function> it is
-    <interfacename>org.freedesktop.hostname1.set-static-hostname</interfacename>. For
-    <function>SetIconName()</function> and <function>SetChassis()</function> it is
-    <interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para>
+  <refsect1>
+    <title>Recommendations</title>
 
-    <para>Here are three examples show how the pretty hostname and the icon name should be used:
+    <para>Here are three examples that show how the pretty hostname and the icon name should be used:
     <itemizedlist>
-      <listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and
-      pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server
-      icon on each service. This is especially useful for WebDAV applications or UPnP media sharing.
+      <listitem><para>When registering DNS-SD services: use the pretty hostname in the service name, and pass
+      the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon
+      on each service. This is especially useful for WebDAV applications or UPnP media sharing.
       </para></listitem>
 
       <listitem><para>Set the bluetooth name to the pretty hostname.</para></listitem>
 
-      <listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set.</para></listitem>
+      <listitem><para>When your file browser has a "Computer" icon, replace the name with the pretty hostname
+      if set, and the icon with the icon name, if it is set.</para></listitem>
     </itemizedlist></para>
 
     <para>To properly handle name lookups with changing local hostnames without having to edit
-    <filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in
-    combination with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    <filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in combination
+    with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     </para>
 
+    <para>A client that wants to change the local hostname for DHCP/mDNS should invoke
+    <code>SetHostname("newname", false)</code> as soon as the name is available and afterwards reset it via
+    <code>SetHostname("")</code>.</para>
+
     <para>Here are some recommendations to follow when generating a static (internet) hostname from a pretty
     name:
     <itemizedlist>
@@ -314,7 +323,7 @@ node /org/freedesktop/hostname1 {
     </itemizedlist></para>
 
     <para>Of course, an already valid internet hostname label you enter and pass through this
-    conversion should stay unmodified, so that users have direct control of it, if they want -- by simply
+    conversion should stay unmodified, so that users have direct control of it, if they want — by simply
     ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet
     name.</para>
   </refsect1>
-- 
2.39.2