man/hostnamectl,hostaned,hostname1: adjust the docs to match reality

The semantics were significantly changed in c779a44222161155c039a7fd2fd304c006590ac7
("hostnamed: Fix the way that static and transient host names interact", Feb. 2014),
but when the dbus api documentation was imported much later, it wasn't properly
adjusted to describe those new semantics.

34293dfafd2a81d80727938199769906dab321bd which added systemd.hostname= also
added new behaviour.

Let's ove various bits and pieces around so that they are in more appropriate
places. Drop recommendations to set the hostname for DHCP or mDNS purposes.
Nowadays we expect tools that want to expose some different hostname to the
outside to manage that internally without affecting visible state. Also drop
mentions of DHCP or mDNS directly setting the hostname, since nowadays network
management software is expected to (and does) go through hostnamed.

Also, add a high-level description of semantics. It glosses over the details of
handling of localhost-style names. Later commits will remove this special handling
anyway.

1 files changed, 11 insertions, 21 deletions

diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml
index 8c00867e73..f50cefa217 100644
--- a/man/hostnamectl.xml
+++ b/man/hostnamectl.xml
@@ -32,33 +32,23 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>hostnamectl</command> may be used to query and
-    change the system hostname and related settings.</para>
-
-    <para>This tool distinguishes three different hostnames: the
-    high-level "pretty" hostname which might include all kinds of
-    special characters (e.g. "Lennart's Laptop"), the static hostname
-    which is used to initialize the kernel hostname at boot (e.g.
-    "lennarts-laptop"), and the transient hostname which is a fallback
-    value received from network configuration. If a static hostname is
-    set, and is valid (something other than localhost), then the
-    transient hostname is not used.</para>
+    <para><command>hostnamectl</command> may be used to query and change the system hostname and related
+    settings.</para>
+
+    <para><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    and this tool distinguish three different hostnames: the high-level "pretty" hostname which might include
+    all kinds of special characters (e.g. "Lennart's Laptop"), the "static" hostname which is the
+    user-configured hostname (e.g. "lennarts-laptop"), and the transient hostname which is a fallback value
+    received from network configuration (e.g. "node12345678"). If a static hostname is set, and is valid
+    (something other than localhost), then the transient hostname is not used.</para>
 
     <para>Note that the pretty hostname has little restrictions on the characters and length used, while the static and
     transient hostnames are limited to the usually accepted characters of Internet domain names, and 64 characters at
     maximum (the latter being a Linux limitation).</para>
 
-    <para>The static hostname is stored in
-    <filename>/etc/hostname</filename>, see
-    <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    for more information. The pretty hostname, chassis type, and icon
-    name are stored in <filename>/etc/machine-info</filename>, see
-    <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
-
     <para>Use
-    <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    to initialize the system hostname for mounted (but not booted)
-    system images.</para>
+    <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> to
+    initialize the system hostname for mounted (but not booted) system images.</para>
   </refsect1>
 
   <refsect1>