The semantics were significantly changed in c779a44222
("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.
34293dfafd 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.