man: various tweaks to org.freedesktop.hostname1(5)

Co-Authored-By: Daan De Meyer <daan.j.demeyer@gmail.com>

man/org.freedesktop.hostname1.xml

@@ -29,7 +29,7 @@
 
     <para>
     <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    is a system service that can be used to control the host name and related machine meta data from user
+    is a system service that can be used to control the hostname and related machine metadata from user
     programs. This page describes the hostname semantics and the D-Bus interface.</para>
   </refsect1>
 
@@ -121,7 +121,7 @@ node /org/freedesktop/hostname1 {
 
     <!--property HomeURL is not documented!-->
 
-    <para>Whenever the hostname or other meta data is changed via the daemon,
+    <para>Whenever the hostname or other metadata is changed via the daemon,
     <function>PropertyChanged</function> signals are sent out to subscribed clients. Changing a hostname
     using this interface is authenticated via PolicyKit.</para>
   </refsect1>
@@ -129,73 +129,73 @@ node /org/freedesktop/hostname1 {
   <refsect1>
     <title>Semantics</title>
 
-    <para>The <emphasis>static (configured) host name</emphasis> is the one configured in
+    <para>The <emphasis>static (configured) hostname</emphasis> is the one configured in
     <filename>/etc/hostname</filename>. It is chosen by the local user. It is not always in sync with the
     current hostname as returned by the
     <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    system call. If no host name is configured this property will be the empty string. Setting this property
+    system call. If no hostname is configured this property will be the empty string. Setting this property
-    to the empty string will remove <filename>/etc/hostname</filename>. This hostname should be an
+    to the empty string will remove <filename>/etc/hostname</filename>. This property should be an
     internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para>
 
-    <para>The <emphasis>transient (dynamic) host name</emphasis> is the one configured via the kernel's
+    <para>The <emphasis>transient (dynamic) hostname</emphasis> is the one configured via the kernel's
     <citerefentry project="man-pages"><refentrytitle>sethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
-    It can be different from the static hostname in case DHCP or mDNS have been configured to change the name
+    It can be different from the static hostname if DHCP or mDNS have been configured to change the name
     based on network information. <!-- FIXME: it's not DHCP that configures this... -->
     This property is never empty. If no hostname is set this will default to
     <literal>&FALLBACK_HOSTNAME;</literal> (configurable at compilation time). Setting this property to the
-    empty string will reset the dynamic hostname to the static host name. If no static host name is
+    empty string will reset the dynamic hostname to the static hostname. If no static hostname is
-    configured the dynamic host name will be reset to <literal>&FALLBACK_HOSTNAME;</literal>. This hostname
+    configured the dynamic hostname will be reset to <literal>&FALLBACK_HOSTNAME;</literal>. This property
     should be an internet-style hostname, 7-bit lowercase ASCII, no special chars/spaces.</para>
 
-    <para>The <emphasis>pretty host name</emphasis> is a free-form UTF-8 host name for presentation to the
+    <para>The <emphasis>pretty hostname</emphasis> is a free-form UTF-8 hostname for presentation to the
     user. User interfaces should ensure that the pretty hostname and the static hostname stay in sync.
     I.e. when the former is <literal>Lennart’s Computer</literal> the latter should be
-    <literal>lennarts-computer</literal>. If no pretty host name is set this setting will be the empty
+    <literal>lennarts-computer</literal>. If no pretty hostname is set this setting will be the empty
     string. Applications should then find a suitable fallback, such as the dynamic hostname.</para>
 
     <para>The <emphasis>icon name</emphasis> is a name following the XDG icon naming spec. If not set,
     information such as the chassis type (see below) is used to find a suitable fallback icon name
     (i.e. <literal>computer-laptop</literal> vs. <literal>computer-desktop</literal> is picked based on the
-    chassis information). If no such data is available, returns the empty string. In that case an application
+    chassis information). If no such data is available, the empty string is returned. In that case an application
     should fall back to a replacement icon, for example <literal>computer</literal>. If this property is set
-    to the empty string, this automatic fallback name selection is enabled again.</para>
+    to the empty string, the automatic fallback name selection is enabled again.</para>
 
-    <para>The <emphasis>chassis type</emphasis> should be one of the following that are currently defined:
+    <para>The <emphasis>chassis type</emphasis> should be one of the currently defined chassis types:
     <literal>desktop</literal>, <literal>laptop</literal>, <literal>server</literal>,
     <literal>tablet</literal>, <literal>handset</literal>, as well as the special chassis types
     <literal>vm</literal> and <literal>container</literal> for virtualized systems. Note that in most cases
     the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to
-    this setting is hence useful only to override misdetected chassis types, or configure a chassis type if
+    this setting is hence useful only to override misdetected chassis types, or to configure the chassis type if
-    none could be auto-detected. Set this property to the empty string to reenable the automatic detection of
+    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 which wants to change the local host name for DHCP/mDNS should invoke
+    <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
-    actually intended behavior: manual configuration changes should require manual reloading of them.</para>
+    the intended behavior: manual configuration changes should require manual reloading.</para>
 
-    <para>The transient (dynamic) hostname directly maps to the kernel hostname. This hostname should be
+    <para>The transient (dynamic) hostname maps directly to the kernel hostname. This hostname should be
-    assumed to be highly dynamic, and hence should be watched directly, without involving
+    assumed to be highly dynamic, and hence should be watched directly, without depending on
-    <function>PropertyChanged</function> messages from <filename>systemd-hostnamed</filename>. For that, open
+    <function>PropertyChanged</function> messages from <filename>systemd-hostnamed</filename>. To accomplish
-    <filename>/proc/sys/kernel/hostname</filename> and
+    this, open <filename>/proc/sys/kernel/hostname</filename> and
     <citerefentry project="man-pages"><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     for <constant>SIGHUP</constant> which is triggered by the kernel every time the hostname changes. Again:
     this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed)
     hostname.</para>
 
-    <para>Applications may bypass the daemon to read the hostname data if notifications of host name changes
+    <para>Applications may read the hostname data directly if hostname change notifications
     are not necessary. Use
     <citerefentry project="man-pages"><refentrytitle>gethostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <filename>/etc/hostname</filename> (possibly with per-distribution fallbacks), and
     <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 user_interaction boolean parameters can be used to control whether PolicyKit should
+    <para>The <varname>user_interaction</varname> boolean parameters can be used to control whether PolicyKit
-    interactively ask the user for authentication credentials if it needs to.</para>
+    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
@@ -204,20 +204,20 @@ node /org/freedesktop/hostname1 {
     <function>SetIconName()</function> and <function>SetChassis()</function> it is
     <interfacename>org.freedesktop.hostname1.set-machine-info</interfacename>.</para>
 
-    <para>Here are three examples how the pretty hostname and the icon name should be used:
+    <para>Here are three examples show how the pretty hostname and the icon name should be used:
     <itemizedlist>
-      <listitem><para>When registering DNS-SD services: use the pretty host name in the service name, and
+      <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. Especially useful for WebDAV stuff. Similar for UPnP media
+      icon on each service. This is especially useful for WebDAV applications or UPnP media sharing.
-      sharing.</para></listitem>
+      </para></listitem>
 
-      <listitem><para>Set the bluetooth name to the pretty host name.</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>
     </itemizedlist></para>
 
     <para>To properly handle name lookups with changing local hostnames without having to edit
-    <filename>/etc/hosts</filename> for them, we recommend using <filename>systemd-hostnamed</filename> in
+    <filename>/etc/hosts</filename>, we recommend using <filename>systemd-hostnamed</filename> in
     combination with <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     </para>
 
@@ -225,13 +225,13 @@ node /org/freedesktop/hostname1 {
     name:
     <itemizedlist>
       <listitem><para>Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them,
-      or replace them by <literal>-</literal>.</para></listitem>
+      or replace them with <literal>-</literal>.</para></listitem>
 
-      <listitem><para>It's probably safer not to use any non-ASCII chars, even if DNS allows this in some way
+      <listitem><para>It's probably safer to not use any non-ASCII chars, even if DNS allows this in some way
       these days. In fact, restrict your charset to <literal>a-zA-Z0-9</literal> and <literal>-</literal>.
       Strip other chars, or try to replace them in some smart way with chars from this set, for example
-      <literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as replacement for all kinds
+      <literal>ä</literal> → <literal>ae</literal>, and use <literal>-</literal> as the replacement for all
-      of punctuation chars or spaces.</para></listitem>
+      punctuation characters and whitespace.</para></listitem>
 
       <listitem><para>Try to avoid creating repeated <literal>-</literal>, as well as <literal>-</literal> as
       the first or last char.</para></listitem>
@@ -239,17 +239,18 @@ node /org/freedesktop/hostname1 {
       <listitem><para>Limit the hostname to 63 chars, which is the length of a DNS label.</para></listitem>
 
       <listitem><para>If after stripping special chars the empty string is the result, you can pass this
-      as-is to <filename>systemd-hostnamed</filename> in which case it will automatically make
+      as-is to <filename>systemd-hostnamed</filename> in which case it will automatically use
-      <literal>&FALLBACK_HOSTNAME;</literal> out of this.</para></listitem>
+      <literal>&FALLBACK_HOSTNAME;</literal>.</para></listitem>
 
-      <listitem><para>It probably is a good idea to replace uppercase by lowercase chars.</para></listitem>
+      <listitem><para>Uppercase charaacters should be replaced with their lowercase equivalents.
+      </para></listitem>
     </itemizedlist></para>
 
     <para>Note that while <filename>systemd-hostnamed</filename> applies some checks to the hostname you pass
     they are much looser than the recommendations above. For example, <filename>systemd-hostnamed</filename>
-    will also accept <literal>_</literal> in the hostname, but I'd recommend not using this to avoid clashes
+    will also accept <literal>_</literal> in the hostname, but we recommend not using this to avoid clashes
     with DNS-SD service types. Also <filename>systemd-hostnamed</filename> allows longer hostnames, but
-    because of the DNS label limitations, I'd recommend not making use of this.</para>
+    because of the DNS label limitations, we recommend not making use of this.</para>
 
     <para>Here are a couple of example conversions:
     <itemizedlist>
@@ -262,7 +263,7 @@ node /org/freedesktop/hostname1 {
       <listitem><para><literal>...zack!!! zack!...</literal> → <literal>zack-zack</literal></para></listitem>
     </itemizedlist></para>
 
-    <para>Oh, and of course, an already valid internet hostname label you enter and pass through this
+    <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
     ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet
     name.</para>