From a7c0e5d714512dc3f9fe30c136778257246f3279 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 26 Nov 2013 02:25:34 +0100
Subject: [PATCH] man: explain the precise syntax and feature set of unit names
 at the end of the man page, given that it is detail information

---
 man/systemctl.xml | 35 ++++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 13 deletions(-)

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 58b2c2ad9..567f39839 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -63,19 +63,6 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
     introspect and control the state of the
     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     system and service manager.</para>
-
-    <para>For unit commands, the <replaceable>NAME</replaceable> represents full name of the unit.
-    <programlisting>
-systemctl start foo.service
-    </programlisting>
-    For unit file commands, the <replaceable>NAME</replaceable> represents the full name of the unit file, or the absolute path to the unit file.
-    <programlisting>
-systemctl start /path/to/foo.service
-    </programlisting>
-    While working with services/service files, <command>systemctl</command> implicitly appends the ".service" suffix when it is missing.
-    <programlisting>
-systemctl start foo
-    </programlisting></para>
   </refsect1>
 
   <refsect1>
@@ -1307,6 +1294,28 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
       </variablelist>
     </refsect2>
 
+    <refsect2>
+      <title>Parameter Syntax</title>
+
+    <para>For unit commands the specified
+    <replaceable>NAME</replaceable> should be the full name of the
+    unit, or an abbreviated name which is automatically extended with
+    the <literal>.service</literal> suffix.
+    <programlisting># systemctl start foo.service</programlisting> is equivalent to:
+    <programlisting># systemctl start foo</programlisting>
+    Note that (absolute) paths to device nodes are automatically converted to device unit names, and other (absolute) paths to mount unit names.
+    <programlisting># systemctl status /dev/sda
+# systemctl status /home</programlisting> is equivalent to:
+    <programlisting># systemctl status dev-sda.device
+# systemctl status home.mount</programlisting></para>
+
+    <para>For unit file commands the
+    specified <replaceable>NAME</replaceable> should be the full name
+    of the unit file, or the absolute path to the unit file.
+    <programlisting># systemctl link /path/to/foo.service</programlisting>
+    </para>
+    </refsect2>
+
   </refsect1>
 
   <refsect1>
-- 
2.30.2