Help output spring cleaning

Use [brackets] only for optional elements.
Use <optional> in XML sources.

7 files changed, 112 insertions, 113 deletions

diff --git a/man/loginctl.xml b/man/loginctl.xml
index d9e9859001..eb4a2fd77a 100644
--- a/man/loginctl.xml
+++ b/man/loginctl.xml
@@ -201,7 +201,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>session-status [ID...]</command></term>
+                                <term><command>session-status</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Show terse runtime
                                 status information about one or more
@@ -214,7 +214,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>show-session [ID...]</command></term>
+                                <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>
 
                                 <listitem><para>Show properties of one
                                 or more sessions or the manager
@@ -237,7 +237,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>activate [ID...]</command></term>
+                                <term><command>activate</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Activate one or more
                                 sessions. This brings one or more
@@ -248,12 +248,13 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>lock-session [ID...]</command></term>
-                                <term><command>unlock-session [ID...]</command></term>
+                                <term><command>lock-session</command> <replaceable>ID</replaceable>...</term>
+                                <term><command>unlock-session</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Activates/deactivates
                                 the screen lock on one or more
-                                sessions, if the session supports it.</para></listitem>
+                                sessions, if the session supports it.
+                                </para></listitem>
                         </varlistentry>
 
                         <varlistentry>
@@ -262,22 +263,22 @@
 
                                 <listitem><para>Activates/deactivates
                                 the screen lock on all current
-                                sessions supporting
-                                it.</para></listitem>
+                                sessions supporting it.
+                                </para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>terminate-session [ID...]</command></term>
+                                <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>
 
-                                <listitem><para>Terminates a
-                                session. This kills all processes of
-                                the session and deallocates all
-                                resources attached to the
-                                session.</para></listitem>
+                                <listitem><para>Terminates a session.
+                                This kills all processes of the
+                                session and deallocates all resources
+                                attached to the session.
+                                </para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>kill-session [ID...]</command></term>
+                                <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Send a signal to one
                                 or more processes of the session. Use
@@ -295,7 +296,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>user-status [USER...]</command></term>
+                                <term><command>user-status</command> <replaceable>USER</replaceable>...</term>
 
                                 <listitem><para>Show terse runtime
                                 status information about one or more
@@ -303,14 +304,14 @@
                                 intended to generate human-readable
                                 output. If you are looking for
                                 computer-parsable output, use
-                                <command>show-user</command>
-                                instead. Users may be specified by
-                                their usernames or numeric user
-                                IDs.</para></listitem>
+                                <command>show-user</command> instead.
+                                Users may be specified by their
+                                usernames or numeric user IDs.
+                                </para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>show-user [USER...]</command></term>
+                                <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>
 
                                 <listitem><para>Show properties of one
                                 or more users or the manager
@@ -333,13 +334,13 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>enable-linger [USER...]</command></term>
-                                <term><command>disable-linger [USER...]</command></term>
+                                <term><command>enable-linger</command> <replaceable>USER</replaceable>...</term>
+                                <term><command>disable-linger</command> <replaceable>USER</replaceable>...</term>
 
                                 <listitem><para>Enable/disable user
                                 lingering for one or more users. If
                                 enabled for a specific user, a user
-                                manager is spawned for him/her at
+                                manager is spawned for the user at
                                 boot and kept around after
                                 logouts. This allows users who are not
                                 logged in to run long-running
@@ -347,18 +348,18 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>terminate-user [USER...]</command></term>
+                                <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>
 
                                 <listitem><para>Terminates all
                                 sessions of a user. This kills all
                                 processes of all sessions of the user
                                 and deallocates all runtime resources
-                                attached to the
-                                user.</para></listitem>
+                                attached to the user.
+                                </para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>kill-user [USER...]</command></term>
+                                <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>
 
                                 <listitem><para>Send a signal to all
                                 processes of a user. Use
@@ -375,7 +376,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>seat-status [NAME...]</command></term>
+                                <term><command>seat-status</command> <replaceable>NAME</replaceable>...</term>
 
                                 <listitem><para>Show terse runtime
                                 status information about one or more
@@ -388,7 +389,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>show-seat [NAME...]</command></term>
+                                <term><command>show-seat</command> <replaceable>NAME</replaceable>...</term>
 
                                 <listitem><para>Show properties of one
                                 or more seats or the manager
@@ -411,7 +412,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>attach [NAME] [DEVICE...]</command></term>
+                                <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>
 
                                 <listitem><para>Persistently attach
                                 one or more devices to a seat. The
@@ -444,12 +445,12 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>terminate-seat [NAME...]</command></term>
+                                <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>
 
                                 <listitem><para>Terminates all
                                 sessions on a seat. This kills all
-                                processes of all sessions on a seat and
-                                deallocates all runtime resources
+                                processes of all sessions on the seat
+                                and deallocates all runtime resources
                                 attached to them.</para></listitem>
                         </varlistentry>
                 </variablelist>
diff --git a/man/machinectl.xml b/man/machinectl.xml
index ec2aaa56d7..6e991ee957 100644
--- a/man/machinectl.xml
+++ b/man/machinectl.xml
@@ -202,7 +202,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>status [ID...]</command></term>
+                                <term><command>status</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Show terse runtime
                                 status information about one or more
@@ -215,7 +215,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>show [ID...]</command></term>
+                                <term><command>show</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Show properties of one
                                 or more registered virtual machines or
@@ -239,7 +239,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>terminate [ID...]</command></term>
+                                <term><command>terminate</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Terminates a virtual
                                 machine or container. This kills all
@@ -250,7 +250,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>kill [ID...]</command></term>
+                                <term><command>kill</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Send a signal to one
                                 or more processes of the virtual
@@ -265,7 +265,7 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term><command>login [ID]</command></term>
+                                <term><command>login</command> <replaceable>ID</replaceable>...</term>
 
                                 <listitem><para>Open a terminal login
                                 session to a container. This will
diff --git a/man/systemctl.xml b/man/systemctl.xml
index ce2860259f..9cd6e88988 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -526,7 +526,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
 
       <variablelist>
         <varlistentry>
-          <term><command>list-units <optional><replaceable>PATTERN...</replaceable></optional></command></term>
+          <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
 
           <listitem>
             <para>List known units (subject to limitations specified
@@ -539,7 +539,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
         </varlistentry>
 
         <varlistentry>
-          <term><command>list-sockets <optional><replaceable>PATTERN...</replaceable></optional></command></term>
+          <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
 
           <listitem>
             <para>List socket units ordered by the listening address.
@@ -565,7 +565,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
         </varlistentry>
 
         <varlistentry>
-          <term><command>list-timers <optional><replaceable>PATTERN...</replaceable></optional></command></term>
+          <term><command>list-timers <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
 
           <listitem>
             <para>List timer units ordered by the time they elapse
@@ -708,7 +708,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
           </listitem>
         </varlistentry>
         <varlistentry>
-          <term><command>status [<replaceable>NAME</replaceable>...|<replaceable>PID</replaceable>...]</command></term>
+          <term><command>status</command> <optional><replaceable>NAME</replaceable>...|<replaceable>PID</replaceable>...]</optional></term>
 
           <listitem>
             <para>Show terse runtime status information about one or
@@ -724,7 +724,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
           </listitem>
         </varlistentry>
         <varlistentry>
-          <term><command>show [<replaceable>NAME</replaceable>...|<replaceable>JOB</replaceable>...]</command></term>
+          <term><command>show</command> <optional><replaceable>NAME</replaceable>...|<replaceable>JOB</replaceable>...</optional></term>
 
           <listitem>
             <para>Show properties of one or more units, jobs, or the
diff --git a/src/login/loginctl.c b/src/login/loginctl.c
index 5547cb2358..f96a568610 100644
--- a/src/login/loginctl.c
+++ b/src/login/loginctl.c
@@ -1037,29 +1037,29 @@ static int help(void) {
                "     --kill-who=WHO      Who to send signal to\n"
                "  -s --signal=SIGNAL     Which signal to send\n\n"
                "Commands:\n"
-               "  list-sessions                   List sessions\n"
-               "  session-status [ID...]          Show session status\n"
-               "  show-session [ID...]            Show properties of one or more sessions\n"
-               "  activate [ID]                   Activate a session\n"
-               "  lock-session [ID...]            Screen lock one or more sessions\n"
-               "  unlock-session [ID...]          Screen unlock one or more sessions\n"
-               "  lock-sessions                   Screen lock all current sessions\n"
-               "  unlock-sessions                 Screen unlock all current sessions\n"
-               "  terminate-session [ID...]       Terminate one or more sessions\n"
-               "  kill-session [ID...]            Send signal to processes of a session\n"
-               "  list-users                      List users\n"
-               "  user-status [USER...]           Show user status\n"
-               "  show-user [USER...]             Show properties of one or more users\n"
-               "  enable-linger [USER...]         Enable linger state of one or more users\n"
-               "  disable-linger [USER...]        Disable linger state of one or more users\n"
-               "  terminate-user [USER...]        Terminate all sessions of one or more users\n"
-               "  kill-user [USER...]             Send signal to processes of a user\n"
-               "  list-seats                      List seats\n"
-               "  seat-status [NAME...]           Show seat status\n"
-               "  show-seat [NAME...]             Show properties of one or more seats\n"
-               "  attach [NAME] [DEVICE...]       Attach one or more devices to a seat\n"
-               "  flush-devices                   Flush all device associations\n"
-               "  terminate-seat [NAME...]        Terminate all sessions on one or more seats\n",
+               "  list-sessions            List sessions\n"
+               "  session-status ID...     Show session status\n"
+               "  show-session [ID...]     Show properties of sessions or the manager\n"
+               "  activate ID              Activate a session\n"
+               "  lock-session ID...       Screen lock one or more sessions\n"
+               "  unlock-session ID...     Screen unlock one or more sessions\n"
+               "  lock-sessions            Screen lock all current sessions\n"
+               "  unlock-sessions          Screen unlock all current sessions\n"
+               "  terminate-session ID...  Terminate one or more sessions\n"
+               "  kill-session ID...       Send signal to processes of a session\n"
+               "  list-users               List users\n"
+               "  user-status USER...      Show user status\n"
+               "  show-user [USER...]      Show properties of users or the manager\n"
+               "  enable-linger USER...    Enable linger state of one or more users\n"
+               "  disable-linger USER...   Disable linger state of one or more users\n"
+               "  terminate-user USER...   Terminate all sessions of one or more users\n"
+               "  kill-user USER...        Send signal to processes of a user\n"
+               "  list-seats               List seats\n"
+               "  seat-status NAME...      Show seat status\n"
+               "  show-seat NAME...        Show properties of one or more seats\n"
+               "  attach NAME DEVICE...    Attach one or more devices to a seat\n"
+               "  flush-devices            Flush all device associations\n"
+               "  terminate-seat NAME...   Terminate all sessions on one or more seats\n",
                program_invocation_short_name);
 
         return 0;
diff --git a/src/machine/machinectl.c b/src/machine/machinectl.c
index 61fb81381c..7bb7086056 100644
--- a/src/machine/machinectl.c
+++ b/src/machine/machinectl.c
@@ -639,11 +639,11 @@ static int help(void) {
                "  -s --signal=SIGNAL     Which signal to send\n\n"
                "Commands:\n"
                "  list                   List running VMs and containers\n"
-               "  status [NAME...]       Show VM/container status\n"
-               "  show [NAME...]         Show properties of one or more VMs/containers\n"
-               "  terminate [NAME...]    Terminate one or more VMs/containers\n"
-               "  kill [NAME...]         Send signal to processes of a VM/container\n"
-               "  login [NAME]           Get a login prompt on a container\n",
+               "  status NAME...         Show VM/container status\n"
+               "  show NAME...           Show properties of one or more VMs/containers\n"
+               "  terminate NAME...      Terminate one or more VMs/containers\n"
+               "  kill NAME...           Send signal to processes of a VM/container\n"
+               "  login NAME             Get a login prompt on a container\n",
                program_invocation_short_name);
 
         return 0;
diff --git a/src/systemctl/systemctl.c b/src/systemctl/systemctl.c
index 16dfddb8e5..2022f13233 100644
--- a/src/systemctl/systemctl.c
+++ b/src/systemctl/systemctl.c
@@ -4839,26 +4839,25 @@ static int systemctl_help(void) {
                "  list-units [PATTERN...]         List loaded units\n"
                "  list-sockets [PATTERN...]       List loaded sockets ordered by address\n"
                "  list-timers [PATTERN...]        List loaded timers ordered by next elapse\n"
-               "  start [NAME...]                 Start (activate) one or more units\n"
-               "  stop [NAME...]                  Stop (deactivate) one or more units\n"
-               "  reload [NAME...]                Reload one or more units\n"
-               "  restart [NAME...]               Start or restart one or more units\n"
-               "  try-restart [NAME...]           Restart one or more units if active\n"
-               "  reload-or-restart [NAME...]     Reload one or more units if possible,\n"
+               "  start NAME...                   Start (activate) one or more units\n"
+               "  stop NAME...                    Stop (deactivate) one or more units\n"
+               "  reload NAME...                  Reload one or more units\n"
+               "  restart NAME...                 Start or restart one or more units\n"
+               "  try-restart NAME...             Restart one or more units if active\n"
+               "  reload-or-restart NAME...       Reload one or more units if possible,\n"
                "                                  otherwise start or restart\n"
-               "  reload-or-try-restart [NAME...] Reload one or more units if possible,\n"
+               "  reload-or-try-restart NAME...   Reload one or more units if possible,\n"
                "                                  otherwise restart if active\n"
-               "  isolate [NAME]                  Start one unit and stop all others\n"
-               "  kill [NAME...]                  Send signal to processes of a unit\n"
-               "  is-active [NAME...]             Check whether units are active\n"
-               "  is-failed [NAME...]             Check whether units are failed\n"
+               "  isolate NAME                    Start one unit and stop all others\n"
+               "  kill NAME...                    Send signal to processes of a unit\n"
+               "  is-active NAME...               Check whether units are active\n"
+               "  is-failed NAME...               Check whether units are failed\n"
                "  status [NAME...|PID...]         Show runtime status of one or more units\n"
                "  show [NAME...|JOB...]           Show properties of one or more\n"
                "                                  units/jobs or the manager\n"
-               "  cat [NAME...]                   Show files and drop-ins of one or more units\n"
-               "  set-property [NAME] [ASSIGNMENT...]\n"
-               "                                  Sets one or more properties of a unit\n"
-               "  help [NAME...|PID...]           Show manual for one or more units\n"
+               "  cat NAME...                     Show files and drop-ins of one or more units\n"
+               "  set-property NAME ASSIGNMENT... Sets one or more properties of a unit\n"
+               "  help NAME...|PID...             Show manual for one or more units\n"
                "  reset-failed [NAME...]          Reset failed state for all, one, or more\n"
                "                                  units\n"
                "  list-dependencies [NAME]        Recursively show units which are required\n"
@@ -4866,15 +4865,15 @@ static int systemctl_help(void) {
                "                                  unit is required or wanted\n\n"
                "Unit File Commands:\n"
                "  list-unit-files [PATTERN...]    List installed unit files\n"
-               "  enable [NAME...]                Enable one or more unit files\n"
-               "  disable [NAME...]               Disable one or more unit files\n"
-               "  reenable [NAME...]              Reenable one or more unit files\n"
-               "  preset [NAME...]                Enable/disable one or more unit files\n"
+               "  enable NAME...                  Enable one or more unit files\n"
+               "  disable NAME...                 Disable one or more unit files\n"
+               "  reenable NAME...                Reenable one or more unit files\n"
+               "  preset NAME...                  Enable/disable one or more unit files\n"
                "                                  based on preset configuration\n"
-               "  is-enabled [NAME...]            Check whether unit files are enabled\n\n"
-               "  mask [NAME...]                  Mask one or more units\n"
-               "  unmask [NAME...]                Unmask one or more units\n"
-               "  link [PATH...]                  Link one or more units files into\n"
+               "  is-enabled NAME...              Check whether unit files are enabled\n\n"
+               "  mask NAME...                    Mask one or more units\n"
+               "  unmask NAME...                  Unmask one or more units\n"
+               "  link PATH...                    Link one or more units files into\n"
                "                                  the search path\n"
                "  get-default                     Get the name of the default target\n"
                "  set-default NAME                Set the default target\n\n"
@@ -4883,11 +4882,11 @@ static int systemctl_help(void) {
                "  cancel [JOB...]                 Cancel all, one, or more jobs\n\n"
                "Snapshot Commands:\n"
                "  snapshot [NAME]                 Create a snapshot\n"
-               "  delete [NAME...]                Remove one or more snapshots\n\n"
+               "  delete NAME...                  Remove one or more snapshots\n\n"
                "Environment Commands:\n"
                "  show-environment                Dump environment\n"
-               "  set-environment [NAME=VALUE...] Set one or more environment variables\n"
-               "  unset-environment [NAME...]     Unset one or more environment variables\n\n"
+               "  set-environment NAME=VALUE...   Set one or more environment variables\n"
+               "  unset-environment NAME...       Unset one or more environment variables\n\n"
                "Manager Lifecycle Commands:\n"
                "  daemon-reload                   Reload systemd manager configuration\n"
                "  daemon-reexec                   Reexecute systemd manager\n\n"
@@ -4900,7 +4899,7 @@ static int systemctl_help(void) {
                "  reboot [ARG]                    Shut down and reboot the system\n"
                "  kexec                           Shut down and reboot the system with kexec\n"
                "  exit                            Request user instance exit\n"
-               "  switch-root [ROOT] [INIT]       Change to a different root file system\n"
+               "  switch-root ROOT [INIT]         Change to a different root file system\n"
                "  suspend                         Suspend the system\n"
                "  hibernate                       Hibernate the system\n"
                "  hybrid-sleep                    Hibernate and suspend the system\n",
diff --git a/src/timedate/timedatectl.c b/src/timedate/timedatectl.c
index 6a36af04f7..6e0bc3cf83 100644
--- a/src/timedate/timedatectl.c
+++ b/src/timedate/timedatectl.c
@@ -410,21 +410,20 @@ static int help(void) {
 
         printf("%s [OPTIONS...] COMMAND ...\n\n"
                "Query or change system time and date settings.\n\n"
-               "  -h --help              Show this help\n"
-               "     --version           Show package version\n"
-               "     --no-pager          Do not pipe output into a pager\n"
-               "     --no-ask-password   Do not prompt for password\n"
-               "  -H --host=[USER@]HOST  Operate on remote host\n"
-               "  -M --machine=CONTAINER Operate on local container\n"
-               "     --adjust-system-clock\n"
-               "                         Adjust system clock when changing local RTC mode\n\n"
+               "  -h --help                Show this help\n"
+               "     --version             Show package version\n"
+               "     --no-pager            Do not pipe output into a pager\n"
+               "     --no-ask-password     Do not prompt for password\n"
+               "  -H --host=[USER@]HOST    Operate on remote host\n"
+               "  -M --machine=CONTAINER   Operate on local container\n"
+               "     --adjust-system-clock Adjust system clock when changing local RTC mode\n\n"
                "Commands:\n"
-               "  status                 Show current time settings\n"
-               "  set-time TIME          Set system time\n"
-               "  set-timezone ZONE      Set system timezone\n"
-               "  list-timezones         Show known timezones\n"
-               "  set-local-rtc BOOL     Control whether RTC is in local time\n"
-               "  set-ntp BOOL           Control whether NTP is enabled\n",
+               "  status                   Show current time settings\n"
+               "  set-time TIME            Set system time\n"
+               "  set-timezone ZONE        Set system timezone\n"
+               "  list-timezones           Show known timezones\n"
+               "  set-local-rtc BOOL       Control whether RTC is in local time\n"
+               "  set-ntp BOOL             Control whether NTP is enabled\n",
                program_invocation_short_name);
 
         return 0;