tree-wide: clean up --help texts a bit

This cleans up and unifies the outut of --help texts a bit:

1. Highlight the human friendly description string, not the command
   line via ANSI sequences. Previously both this description string and
   the brief command line summary was marked with the same ANSI
   highlight sequence, but given we auto-page to less and less does not
   honour multi-line highlights only the command line summary was
   affectively highlighted. Rationale: for highlighting the description
   instead of the command line: the command line summary is relatively
   boring, and mostly the same for out tools, the description on the
   other hand is pregnant, important and captions the whole thing and
   hence deserves highlighting.

2. Always suffix "Options" with ":" in the help text

3. Rename "Flags" →  "Options" in one case

4. Move commands to the top in a few cases

5. add coloring to many more help pages

6. Unify on COMMAND instead of {COMMAND} in the command line summary.
   Some tools did it one way, others the other way. I am not sure what
   precisely {} is supposed to mean, that uppercasing doesn't, hence
   let's simplify and stick to the {}-less syntax

And minor other tweaks.

diff --git a/src/activate/activate.c b/src/activate/activate.c
index 9948520..77b9a05 100644 (file)
--- a/src/activate/activate.c
+++ b/src/activate/activate.c
@@ -332,9 +332,9 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...]\n\n"
-               "Listen on sockets and launch child on connection.\n\n"
-               "Options:\n"
+        printf("%s [OPTIONS...]\n"
+               "\n%sListen on sockets and launch child on connection.%s\n"
+               "\nOptions:\n"
                "  -h --help                  Show this help and exit\n"
                "     --version               Print version string and exit\n"
                "  -l --listen=ADDR           Listen for raw connections at ADDR\n"
@@ -347,6 +347,7 @@ static int help(void) {
                "\nNote: file descriptors from sd_listen_fds() will be passed through.\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight(), ansi_normal()
                , link
         );
 

diff --git a/src/analyze/analyze.c b/src/analyze/analyze.c
index 9421196..c7f7427 100644 (file)
--- a/src/analyze/analyze.c
+++ b/src/analyze/analyze.c
@@ -2243,26 +2243,8 @@ static int help(int argc, char *argv[], void *userdata) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...] {COMMAND} ...\n\n"
-               "Profile systemd, show unit dependencies, check unit files.\n\n"
-               "  -h --help                Show this help\n"
-               "     --version             Show package version\n"
-               "     --no-pager            Do not pipe output into a pager\n"
-               "     --system              Operate on system systemd instance\n"
-               "     --user                Operate on user systemd instance\n"
-               "     --global              Operate on global user configuration\n"
-               "  -H --host=[USER@]HOST    Operate on remote host\n"
-               "  -M --machine=CONTAINER   Operate on local container\n"
-               "     --order               Show only order in the graph\n"
-               "     --require             Show only requirement in the graph\n"
-               "     --from-pattern=GLOB   Show only origins in the graph\n"
-               "     --to-pattern=GLOB     Show only destinations in the graph\n"
-               "     --fuzz=SECONDS        Also print services which finished SECONDS earlier\n"
-               "                           than the latest in the branch\n"
-               "     --man[=BOOL]          Do [not] check for existence of man pages\n"
-               "     --generators[=BOOL]   Do [not] run unit generators (requires privileges)\n"
-               "     --iterations=N        Show the specified number of iterations\n"
-               "     --base-time=TIMESTAMP Calculate calendar times relative to specified time\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sProfile systemd, show unit dependencies, check unit files.%s\n"
                "\nCommands:\n"
                "  time                     Print time spent in the kernel\n"
                "  blame                    Print list of running units ordered by time to init\n"
@@ -2284,8 +2266,29 @@ static int help(int argc, char *argv[], void *userdata) {
                "  timestamp TIMESTAMP...   Validate a timestamp\n"
                "  timespan SPAN...         Validate a time span\n"
                "  security [UNIT...]       Analyze security of unit\n"
+               "\nOptions:\n"
+               "  -h --help                Show this help\n"
+               "     --version             Show package version\n"
+               "     --no-pager            Do not pipe output into a pager\n"
+               "     --system              Operate on system systemd instance\n"
+               "     --user                Operate on user systemd instance\n"
+               "     --global              Operate on global user configuration\n"
+               "  -H --host=[USER@]HOST    Operate on remote host\n"
+               "  -M --machine=CONTAINER   Operate on local container\n"
+               "     --order               Show only order in the graph\n"
+               "     --require             Show only requirement in the graph\n"
+               "     --from-pattern=GLOB   Show only origins in the graph\n"
+               "     --to-pattern=GLOB     Show only destinations in the graph\n"
+               "     --fuzz=SECONDS        Also print services which finished SECONDS earlier\n"
+               "                           than the latest in the branch\n"
+               "     --man[=BOOL]          Do [not] check for existence of man pages\n"
+               "     --generators[=BOOL]   Do [not] run unit generators (requires privileges)\n"
+               "     --iterations=N        Show the specified number of iterations\n"
+               "     --base-time=TIMESTAMP Calculate calendar times relative to specified time\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight()
+               , ansi_normal()
                , dot_link
                , link
         );

diff --git a/src/boot/bless-boot.c b/src/boot/bless-boot.c
index 4747e7f..b96e1f9 100644 (file)
--- a/src/boot/bless-boot.c
+++ b/src/boot/bless-boot.c
@@ -13,6 +13,8 @@
 #include "main-func.h"
 #include "parse-util.h"
 #include "path-util.h"
+#include "pretty-print.h"
+#include "terminal-util.h"
 #include "util.h"
 #include "verbs.h"
 #include "virt.h"
@@ -22,19 +24,29 @@ static char **arg_path = NULL;
 STATIC_DESTRUCTOR_REGISTER(arg_path, strv_freep);
 
 static int help(int argc, char *argv[], void *userdata) {
+        _cleanup_free_ char *link = NULL;
+        int r;
+
+        r = terminal_urlify_man("systemd-bless-boot.service", "8", &link);
+        if (r < 0)
+                return log_oom();
 
-        printf("%s [COMMAND] [OPTIONS...]\n"
-               "\n"
-               "Mark the boot process as good or bad.\n\n"
+        printf("%s [OPTIONS...] COMMAND\n"
+               "\n%sMark the boot process as good or bad.%s\n"
+               "\nCommands:\n"
+               "     good            Mark this boot as good\n"
+               "     bad             Mark this boot as bad\n"
+               "     indeterminate   Undo any marking as good or bad\n"
+               "\nOptions:\n"
                "  -h --help          Show this help\n"
                "     --version       Print version\n"
                "     --path=PATH     Path to the $BOOT partition (may be used multiple times)\n"
-               "\n"
-               "Commands:\n"
-               "     good            Mark this boot as good\n"
-               "     bad             Mark this boot as bad\n"
-               "     indeterminate   Undo any marking as good or bad\n",
-               program_invocation_short_name);
+               "\nSee the %s for details.\n"
+               , program_invocation_short_name
+               , ansi_highlight()
+               , ansi_normal()
+               , link
+        );
 
         return 0;
 }

diff --git a/src/boot/boot-check-no-failures.c b/src/boot/boot-check-no-failures.c
index 3284a04..038ce29 100644 (file)
--- a/src/boot/boot-check-no-failures.c
+++ b/src/boot/boot-check-no-failures.c
@@ -11,16 +11,28 @@
 #include "bus-error.h"
 #include "log.h"
 #include "main-func.h"
+#include "pretty-print.h"
+#include "terminal-util.h"
 #include "util.h"
 
 static int help(void) {
+        _cleanup_free_ char *link = NULL;
+        int r;
+
+        r = terminal_urlify_man("systemd-boot-check-no-failures.service", "8", &link);
+        if (r < 0)
+                return log_oom();
 
-        printf("%s [COMMAND] [OPTIONS...]\n"
-               "\n"
-               "Verify system operational state.\n\n"
+        printf("%s [OPTIONS...]\n"
+               "\n%sVerify system operational state.%s\n\n"
                "  -h --help          Show this help\n"
-               "     --version       Print version\n",
-               program_invocation_short_name);
+               "     --version       Print version\n"
+               "\nSee the %s for details.\n"
+               , program_invocation_short_name
+               , ansi_highlight()
+               , ansi_normal()
+               , link
+        );
 
         return 0;
 }

diff --git a/src/boot/bootctl.c b/src/boot/bootctl.c
index d8e8d8c..d062ac2 100644 (file)
--- a/src/boot/bootctl.c
+++ b/src/boot/bootctl.c
@@ -1032,8 +1032,8 @@ static int help(int argc, char *argv[], void *userdata) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [COMMAND] [OPTIONS...]\n\n"
-               "Install, update or remove the systemd-boot EFI boot manager.\n"
+        printf("%s  [OPTIONS...] COMMAND ...\n"
+               "\n%sInstall, update or remove the systemd-boot EFI boot manager.%s\n"
                "\nBoot Loader Commands:\n"
                "     status            Show status of installed systemd-boot and EFI variables\n"
                "     install           Install systemd-boot to the ESP and EFI variables\n"
@@ -1046,6 +1046,7 @@ static int help(int argc, char *argv[], void *userdata) {
                "     list              List boot loader entries\n"
                "     set-default ID    Set default boot loader entry\n"
                "     set-oneshot ID    Set default boot loader entry, for next boot only\n"
+               "\nOptions:\n"
                "  -h --help            Show this help\n"
                "     --version         Print version\n"
                "     --esp-path=PATH   Path to the EFI System Partition (ESP)\n"
@@ -1056,6 +1057,8 @@ static int help(int argc, char *argv[], void *userdata) {
                "     --no-pager        Do not pipe output into a pager\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight()
+               , ansi_normal()
                , link);
 
         return 0;

diff --git a/src/busctl/busctl.c b/src/busctl/busctl.c
index 3ed8f21..878837e 100644 (file)
--- a/src/busctl/busctl.c
+++ b/src/busctl/busctl.c
@@ -2228,9 +2228,9 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...] {COMMAND} ...\n\n"
-               "Introspect the bus.%s\n\n"
-               "Commands:\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sIntrospect the D-Bus IPC bus.%s\n"
+               "\nCommands:\n"
                "  list                     List bus names\n"
                "  status [SERVICE]         Show bus service, process or bus owner credentials\n"
                "  monitor [SERVICE...]     Show bus traffic\n"
@@ -2277,8 +2277,8 @@ static int help(void) {
                "                           system\n"
                "     --destination=SERVICE Destination service of a signal\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/coredump/coredumpctl.c b/src/coredump/coredumpctl.c
index d68ff1c..ed12464 100644 (file)
--- a/src/coredump/coredumpctl.c
+++ b/src/coredump/coredumpctl.c
@@ -145,14 +145,14 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...]\n\n"
-               "List or retrieve coredumps from the journal.%s\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sList or retrieve coredumps from the journal.%s\n"
                "\nCommands:\n"
                "  list [MATCHES...]  List available coredumps (default)\n"
                "  info [MATCHES...]  Show detailed information about one or more coredumps\n"
                "  dump [MATCHES...]  Print first matching coredump to stdout\n"
                "  debug [MATCHES...] Start a debugger for the first matching coredump\n"
-               "\nFlags:\n"
+               "\nOptions:\n"
                "  -h --help              Show this help\n"
                "     --version           Print version string\n"
                "     --no-pager          Do not pipe output into a pager\n"
@@ -167,8 +167,8 @@ static int help(void) {
                "  -D --directory=DIR     Use journal files from directory\n\n"
                "  -q --quiet             Do not show info messages and privilege warning\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/hostname/hostnamectl.c b/src/hostname/hostnamectl.c
index d98812d..5596846 100644 (file)
--- a/src/hostname/hostnamectl.c
+++ b/src/hostname/hostnamectl.c
@@ -310,8 +310,8 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...] COMMAND ...\n\n"
-               "Query or change system hostname.%s\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sQuery or change system hostname.%s\n"
                "\nCommands:\n"
                "  status                 Show current hostname settings\n"
                "  set-hostname NAME      Set system hostname\n"
@@ -329,8 +329,8 @@ static int help(void) {
                "     --static            Only set static hostname\n"
                "     --pretty            Only set pretty hostname\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/hwdb/hwdb.c b/src/hwdb/hwdb.c
index b069a3e..651647b 100644 (file)
--- a/src/hwdb/hwdb.c
+++ b/src/hwdb/hwdb.c
@@ -9,6 +9,7 @@
 #include "main-func.h"
 #include "pretty-print.h"
 #include "selinux-util.h"
+#include "terminal-util.h"
 #include "util.h"
 #include "verbs.h"
 
@@ -32,18 +33,21 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s OPTIONS COMMAND\n\n"
-               "Update or query the hardware database.\n\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sUpdate or query the hardware database.%s\n"
+               "\nCommands:\n"
+               "  update          Update the hwdb database\n"
+               "  query MODALIAS  Query database and print result\n"
+               "\nOptions:\n"
                "  -h --help       Show this help\n"
                "     --version    Show package version\n"
                "  -s --strict     When updating, return non-zero exit value on any parsing error\n"
                "     --usr        Generate in " UDEVLIBEXECDIR " instead of /etc/udev\n"
                "  -r --root=PATH  Alternative root path in the filesystem\n\n"
-               "Commands:\n"
-               "  update          Update the hwdb database\n"
-               "  query MODALIAS  Query database and print result\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight()
+               , ansi_normal()
                , link
         );
 

diff --git a/src/journal/cat.c b/src/journal/cat.c
index 376b68a..500b674 100644 (file)
--- a/src/journal/cat.c
+++ b/src/journal/cat.c
@@ -16,6 +16,7 @@
 #include "pretty-print.h"
 #include "string-util.h"
 #include "syslog-util.h"
+#include "terminal-util.h"
 #include "util.h"
 
 static const char *arg_identifier = NULL;
@@ -31,8 +32,8 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...] {COMMAND} ...\n\n"
-               "Execute process with stdout/stderr connected to the journal.\n\n"
+        printf("%s [OPTIONS...] COMMAND ...\n"
+               "\n%sExecute process with stdout/stderr connected to the journal.%s\n\n"
                "  -h --help                      Show this help\n"
                "     --version                   Show package version\n"
                "  -t --identifier=STRING         Set syslog identifier\n"
@@ -41,6 +42,7 @@ static int help(void) {
                "     --level-prefix=BOOL         Control whether level prefix shall be parsed\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight(), ansi_normal()
                , link
         );
 

diff --git a/src/journal/journalctl.c b/src/journal/journalctl.c
index e5a2f6e..aca046d 100644 (file)
--- a/src/journal/journalctl.c
+++ b/src/journal/journalctl.c
@@ -314,7 +314,7 @@ static int help(void) {
                 return log_oom();
 
         printf("%s [OPTIONS...] [MATCHES...]\n\n"
-               "Query the journal.\n\n"
+               "%sQuery the journal.%s\n\n"
                "Options:\n"
                "     --system                Show the system journal\n"
                "     --user                  Show the user journal for the current user\n"
@@ -381,6 +381,7 @@ static int help(void) {
                "     --setup-keys            Generate a new FSS key pair\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight(), ansi_normal()
                , link
         );
 

diff --git a/src/locale/localectl.c b/src/locale/localectl.c
index fb02bfd..6f2d37d 100644 (file)
--- a/src/locale/localectl.c
+++ b/src/locale/localectl.c
@@ -383,16 +383,9 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...] COMMAND ...\n\n"
-               "Query or change system locale and keyboard settings.%s\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"
-               "     --no-convert          Don't convert keyboard mappings\n\n"
-               "Commands:\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sQuery or change system locale and keyboard settings.%s\n"
+               "\nCommands:\n"
                "  status                   Show current locale settings\n"
                "  set-locale LOCALE...     Set system locale\n"
                "  list-locales             Show known locales\n"
@@ -405,9 +398,17 @@ static int help(void) {
                "  list-x11-keymap-variants [LAYOUT]\n"
                "                           Show known X11 keyboard mapping variants\n"
                "  list-x11-keymap-options  Show known X11 keyboard mapping options\n"
+               "\nOptions:\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"
+               "     --no-convert          Don't convert keyboard mappings\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/login/inhibit.c b/src/login/inhibit.c
index 25ff4d0..72d455e 100644 (file)
--- a/src/login/inhibit.c
+++ b/src/login/inhibit.c
@@ -20,6 +20,7 @@
 #include "process-util.h"
 #include "signal-util.h"
 #include "strv.h"
+#include "terminal-util.h"
 #include "user-util.h"
 #include "util.h"
 
@@ -158,8 +159,8 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...] {COMMAND} ...\n\n"
-               "Execute a process while inhibiting shutdown/sleep/idle.\n\n"
+        printf("%s [OPTIONS...] COMMAND ...\n"
+               "\n%sExecute a process while inhibiting shutdown/sleep/idle.%s\n\n"
                "  -h --help               Show this help\n"
                "     --version            Show package version\n"
                "     --no-pager           Do not pipe output into a pager\n"
@@ -174,6 +175,7 @@ static int help(void) {
                "     --list               List active inhibitors\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight(), ansi_normal()
                , link
         );
 

diff --git a/src/login/loginctl.c b/src/login/loginctl.c
index 26681ac..33c96dc 100644 (file)
--- a/src/login/loginctl.c
+++ b/src/login/loginctl.c
@@ -1279,8 +1279,8 @@ static int help(int argc, char *argv[], void *userdata) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...] {COMMAND} ...\n\n"
-               "Send control commands to or query the login manager.%s\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sSend control commands to or query the login manager.%s\n"
                "\nSession Commands:\n"
                "  list-sessions            List sessions\n"
                "  session-status [ID...]   Show session status\n"
@@ -1291,23 +1291,23 @@ static int help(int argc, char *argv[], void *userdata) {
                "  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\n"
-               "User Commands:\n"
+               "  kill-session ID...       Send signal to processes of a session\n"
+               "\nUser Commands:\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\n"
-               "Seat Commands:\n"
+               "  kill-user USER...        Send signal to processes of a user\n"
+               "\nSeat Commands:\n"
                "  list-seats               List seats\n"
                "  seat-status [NAME...]    Show seat status\n"
                "  show-seat [NAME...]      Show properties of seats or the manager\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"
-               "\nOptions\n"
+               "\nOptions:\n"
                "  -h --help                Show this help\n"
                "     --version             Show package version\n"
                "     --no-pager            Do not pipe output into a pager\n"
@@ -1328,8 +1328,8 @@ static int help(int argc, char *argv[], void *userdata) {
                "                             json, json-pretty, json-sse, json-seq, cat,\n"
                "                             with-unit)\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/machine/machinectl.c b/src/machine/machinectl.c
index afb8985..4b02b08 100644 (file)
--- a/src/machine/machinectl.c
+++ b/src/machine/machinectl.c
@@ -2690,9 +2690,9 @@ static int help(int argc, char *argv[], void *userdata) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...] {COMMAND} ...\n\n"
-               "Send control commands to or query the virtual machine and container\n"
-               "registration manager.%s\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sSend control commands to or query the virtual machine and container%s\n"
+               "%sregistration manager.%s\n"
                "\nMachine Commands:\n"
                "  list                        List running VMs and containers\n"
                "  status NAME...              Show VM/container details\n"
@@ -2732,7 +2732,7 @@ static int help(int argc, char *argv[], void *userdata) {
                "  export-raw NAME [FILE]      Export a RAW container or VM image locally\n"
                "  list-transfers              Show list of downloads in progress\n"
                "  cancel-transfer             Cancel a download\n"
-               "\nOptions\n"
+               "\nOptions:\n"
                "  -h --help                   Show this help\n"
                "     --version                Show package version\n"
                "     --no-pager               Do not pipe output into a pager\n"
@@ -2762,8 +2762,10 @@ static int help(int argc, char *argv[], void *userdata) {
                "                              checksum, signature)\n"
                "     --force                  Download image even if already exists\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
+               , ansi_normal()
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/network/networkctl.c b/src/network/networkctl.c
index a43a179..35a78eb 100644 (file)
--- a/src/network/networkctl.c
+++ b/src/network/networkctl.c
@@ -1887,8 +1887,8 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...]\n\n"
-               "Query and control the networking subsystem.%s\n"
+        printf("%s [OPTIONS...] COMMAND\n\n"
+               "%sQuery and control the networking subsystem.%s\n"
                "\nCommands:\n"
                "  list [PATTERN...]      List links\n"
                "  status [PATTERN...]    Show link status\n"
@@ -1898,7 +1898,7 @@ static int help(void) {
                "  renew DEVICES...       Renew dynamic configurations\n"
                "  reconfigure DEVICES... Reconfigure interfaces\n"
                "  reload                 Reload .network and .netdev files\n"
-               "\nOptions\n"
+               "\nOptions:\n"
                "  -h --help              Show this help\n"
                "     --version           Show package version\n"
                "     --no-pager          Do not pipe output into a pager\n"
@@ -1906,8 +1906,8 @@ static int help(void) {
                "  -a --all               Show status for all links\n"
                "  -s --stats             Show detailed link statics\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/portable/portablectl.c b/src/portable/portablectl.c
index 06ab773..7246c6c 100644 (file)
--- a/src/portable/portablectl.c
+++ b/src/portable/portablectl.c
@@ -781,9 +781,9 @@ static int help(int argc, char *argv[], void *userdata) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...] {COMMAND} ...\n\n"
-               "Attach or detach portable services from the local system.%s\n"
-               "Commands:\n"
+        printf("%s [OPTIONS...] COMMAND ...\n\n"
+               "%sAttach or detach portable services from the local system.%s\n"
+               "\nCommands:\n"
                "  list                        List available portable service images\n"
                "  attach NAME|PATH [PREFIX...]\n"
                "                              Attach the specified portable service image\n"
@@ -794,7 +794,7 @@ static int help(int argc, char *argv[], void *userdata) {
                "  read-only NAME|PATH [BOOL]  Mark or unmark portable service image read-only\n"
                "  remove NAME|PATH...         Remove a portable service image\n"
                "  set-limit [NAME|PATH]       Set image or pool size limit (disk quota)\n"
-               "\nOptions\n"
+               "\nOptions:\n"
                "  -h --help                   Show this help\n"
                "     --version                Show package version\n"
                "     --no-pager               Do not pipe output into a pager\n"
@@ -810,8 +810,8 @@ static int help(int argc, char *argv[], void *userdata) {
                "     --cat                    When inspecting include unit and os-release file\n"
                "                              contents\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/resolve/resolvectl.c b/src/resolve/resolvectl.c
index ec4bffa..0a96a18 100644 (file)
--- a/src/resolve/resolvectl.c
+++ b/src/resolve/resolvectl.c
@@ -2473,7 +2473,7 @@ static int compat_help(void) {
                "%1$s [OPTIONS...] --statistics\n"
                "%1$s [OPTIONS...] --reset-statistics\n"
                "\n"
-               "Resolve domain names, IPv4 and IPv6 addresses, DNS records, and services.\n\n"
+               "%2$sResolve domain names, IPv4 and IPv6 addresses, DNS records, and services.%3$s\n\n"
                "  -h --help                 Show this help\n"
                "     --version              Show package version\n"
                "     --no-pager             Do not pipe output into a pager\n"
@@ -2507,8 +2507,10 @@ static int compat_help(void) {
                "     --set-dnssec=MODE      Set per-interface DNSSEC mode\n"
                "     --set-nta=DOMAIN       Set per-interface DNSSEC NTA\n"
                "     --revert               Revert per-interface configuration\n"
-               "\nSee the %2$s for details.\n"
+               "\nSee the %4$s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight()
+               , ansi_normal()
                , link
         );
 
@@ -2523,10 +2525,10 @@ static int native_help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...] {COMMAND} ...\n"
+        printf("%s [OPTIONS...] COMMAND ...\n"
                "\n"
-               "Send control commands to the network name resolution manager, or\n"
-               "resolve domain names, IPv4 and IPv6 addresses, DNS records, and services.%s\n"
+               "%sSend control commands to the network name resolution manager, or%s\n"
+               "%sresolve domain names, IPv4 and IPv6 addresses, DNS records, and services.%s\n"
                "\nCommands:\n"
                "  query HOSTNAME|ADDRESS...    Resolve domain names, IPv4 and IPv6 addresses\n"
                "  service [[NAME] TYPE] DOMAIN Resolve service (SRV)\n"
@@ -2546,7 +2548,7 @@ static int native_help(void) {
                "  dnssec [LINK [MODE]]         Get/set per-interface DNSSEC mode\n"
                "  nta [LINK [DOMAIN...]]       Get/set per-interface DNSSEC NTA\n"
                "  revert LINK                  Revert per-interface configuration\n"
-               "\nOptions\n"
+               "\nOptions:\n"
                "  -h --help                    Show this help\n"
                "     --version                 Show package version\n"
                "     --no-pager                Do not pipe output into a pager\n"
@@ -2564,8 +2566,10 @@ static int native_help(void) {
                "     --raw[=payload|packet]    Dump the answer as binary data\n"
                "     --legend=BOOL             Print headers and additional info (default: yes)\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
+               , ansi_normal()
+               , ansi_highlight()
                , ansi_normal()
                , link
         );

diff --git a/src/run/run.c b/src/run/run.c
index de968ca..2b806fb 100644 (file)
--- a/src/run/run.c
+++ b/src/run/run.c
@@ -84,8 +84,8 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...] {COMMAND} [ARGS...]\n\n"
-               "Run the specified command in a transient scope or service.\n\n"
+        printf("%s [OPTIONS...] COMMAND [ARGUMENTS...]\n"
+               "\n%sRun the specified command in a transient scope or service.%s\n\n"
                "  -h --help                       Show this help\n"
                "     --version                    Show package version\n"
                "     --no-ask-password            Do not prompt for password\n"
@@ -130,6 +130,7 @@ static int help(void) {
                "     --timer-property=NAME=VALUE  Set timer unit property\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight(), ansi_normal()
                , link
         );
 

diff --git a/src/systemctl/systemctl.c b/src/systemctl/systemctl.c
index 012867f..9200810 100644 (file)
--- a/src/systemctl/systemctl.c
+++ b/src/systemctl/systemctl.c
@@ -7694,9 +7694,9 @@ static int systemctl_help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%5$s%1$s [OPTIONS...] {COMMAND} ...\n\n"
-               "Query or send control commands to the systemd manager.%6$s\n\n"
-               "%3$sUnit Commands:%4$s\n"
+        printf("%1$s [OPTIONS...] COMMAND ...\n\n"
+               "%5$sQuery or send control commands to the system manager.%6$s\n"
+               "\n%3$sUnit Commands:%4$s\n"
                "  list-units [PATTERN...]             List units currently in memory\n"
                "  list-sockets [PATTERN...]           List socket units currently in memory,\n"
                "                                      ordered by address\n"
@@ -7727,8 +7727,8 @@ static int systemctl_help(void) {
                "                                      units\n"
                "  list-dependencies [UNIT]            Recursively show units which are required\n"
                "                                      or wanted by this unit or by which this\n"
-               "                                      unit is required or wanted\n\n"
-               "%3$sUnit File Commands:%4$s\n"
+               "                                      unit is required or wanted\n"
+               "\n%3$sUnit File Commands:%4$s\n"
                "  list-unit-files [PATTERN...]        List installed unit files\n"
                "  enable [UNIT...|PATH...]            Enable one or more unit files\n"
                "  disable UNIT...                     Disable one or more unit files\n"
@@ -7750,21 +7750,21 @@ static int systemctl_help(void) {
                "                                      on specified one or more units\n"
                "  edit UNIT...                        Edit one or more unit files\n"
                "  get-default                         Get the name of the default target\n"
-               "  set-default TARGET                  Set the default target\n\n"
-               "%3$sMachine Commands:%4$s\n"
+               "  set-default TARGET                  Set the default target\n"
+               "\n%3$sMachine Commands:%4$s\n"
                "  list-machines [PATTERN...]          List local containers and host\n\n"
-               "%3$sJob Commands:%4$s\n"
+               "\n%3$sJob Commands:%4$s\n"
                "  list-jobs [PATTERN...]              List jobs\n"
-               "  cancel [JOB...]                     Cancel all, one, or more jobs\n\n"
-               "%3$sEnvironment Commands:%4$s\n"
+               "  cancel [JOB...]                     Cancel all, one, or more jobs\n"
+               "\n%3$sEnvironment Commands:%4$s\n"
                "  show-environment                    Dump environment\n"
                "  set-environment VARIABLE=VALUE...   Set one or more environment variables\n"
                "  unset-environment VARIABLE...       Unset one or more environment variables\n"
                "  import-environment [VARIABLE...]    Import all or some environment variables\n\n"
-               "%3$sManager Lifecycle Commands:%4$s\n"
+               "\n%3$sManager Lifecycle Commands:%4$s\n"
                "  daemon-reload                       Reload systemd manager configuration\n"
-               "  daemon-reexec                       Reexecute systemd manager\n\n"
-               "%3$sSystem Commands:%4$s\n"
+               "  daemon-reexec                       Reexecute systemd manager\n"
+               "\n%3$sSystem Commands:%4$s\n"
                "  is-system-running                   Check whether system is fully running\n"
                "  default                             Enter system default mode\n"
                "  rescue                              Enter system rescue mode\n"
@@ -7780,7 +7780,7 @@ static int systemctl_help(void) {
                "  hybrid-sleep                        Hibernate and suspend the system\n"
                "  suspend-then-hibernate              Suspend the system, wake after a period of\n"
                "                                      time and put it into hibernate\n"
-               "\nOptions\n"
+               "\n%3$sOptions:%4$s\n"
                "  -h --help           Show this help\n"
                "     --version        Show package version\n"
                "     --system         Connect to system manager\n"
@@ -7859,8 +7859,9 @@ static int halt_help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...]%s\n\n"
-               "%s the system.\n\n"
+        printf("%s [OPTIONS...]%s\n"
+               "\n%s%s the system.%s\n"
+               "\nOptions:\n"
                "     --help      Show this help\n"
                "     --halt      Halt the machine\n"
                "  -p --poweroff  Switch off the machine\n"
@@ -7871,10 +7872,12 @@ static int halt_help(void) {
                "     --no-wall   Don't send wall message before halt/power-off/reboot\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
-               , arg_action == ACTION_REBOOT   ? " [ARG]" : "",
-                 arg_action == ACTION_REBOOT   ? "Reboot" :
+               , arg_action == ACTION_REBOOT   ? " [ARG]" : ""
+               , ansi_highlight()
+               , arg_action == ACTION_REBOOT   ? "Reboot" :
                  arg_action == ACTION_POWEROFF ? "Power off" :
                                                  "Halt"
+               , ansi_normal()
                , link
         );
 
@@ -7889,8 +7892,9 @@ static int shutdown_help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...] [TIME] [WALL...]\n\n"
-               "Shut down the system.\n\n"
+        printf("%s [OPTIONS...] [TIME] [WALL...]\n"
+               "\n%sShut down the system.%s\n"
+               "\nOptions:\n"
                "     --help      Show this help\n"
                "  -H --halt      Halt the machine\n"
                "  -P --poweroff  Power-off the machine\n"
@@ -7901,6 +7905,7 @@ static int shutdown_help(void) {
                "  -c             Cancel a pending shutdown\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight(), ansi_normal()
                , link
         );
 
@@ -7915,19 +7920,21 @@ static int telinit_help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...] {COMMAND}\n\n"
-               "Send control commands to the init daemon.\n\n"
-               "     --help      Show this help\n"
-               "     --no-wall   Don't send wall message before halt/power-off/reboot\n\n"
-               "Commands:\n"
+        printf("%s [OPTIONS...] COMMAND\n\n"
+               "%sSend control commands to the init daemon.%s\n"
+               "\nCommands:\n"
                "  0              Power-off the machine\n"
                "  6              Reboot the machine\n"
                "  2, 3, 4, 5     Start runlevelX.target unit\n"
                "  1, s, S        Enter rescue mode\n"
                "  q, Q           Reload init daemon configuration\n"
                "  u, U           Reexecute init daemon\n"
+               "\nOptions:\n"
+               "     --help      Show this help\n"
+               "     --no-wall   Don't send wall message before halt/power-off/reboot\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight(), ansi_normal()
                , link
         );
 
@@ -7942,11 +7949,13 @@ static int runlevel_help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s [OPTIONS...]\n\n"
-               "Prints the previous and current runlevel of the init system.\n\n"
+        printf("%s [OPTIONS...]\n"
+               "\n%sPrints the previous and current runlevel of the init system.%s\n"
+               "\nOptions:\n"
                "     --help      Show this help\n"
                "\nSee the %s for details.\n"
                , program_invocation_short_name
+               , ansi_highlight(), ansi_normal()
                , link
         );
 
@@ -8525,7 +8534,7 @@ static int systemctl_parse_argv(int argc, char *argv[]) {
                         /* Output an error mimicking getopt, and print a hint afterwards */
                         log_error("%s: invalid option -- '.'", program_invocation_name);
                         log_notice("Hint: to specify units starting with a dash, use \"--\":\n"
-                                   "      %s [OPTIONS...] {COMMAND} -- -.%s ...",
+                                   "      %s [OPTIONS...] COMMAND -- -.%s ...",
                                    program_invocation_name, optarg ?: "mount");
                         _fallthrough_;
 

diff --git a/src/timedate/timedatectl.c b/src/timedate/timedatectl.c
index 2a98c48..d31b319 100644 (file)
--- a/src/timedate/timedatectl.c
+++ b/src/timedate/timedatectl.c
@@ -810,8 +810,8 @@ static int help(void) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s%s [OPTIONS...] COMMAND ...\n\n"
-               "Query or change system time and date settings.%s\n"
+        printf("%s [OPTIONS...] COMMAND ...\n"
+               "\n%sQuery or change system time and date settings.%s\n"
                "\nCommands:\n"
                "  status                   Show current time settings\n"
                "  show                     Show properties of systemd-timedated\n"
@@ -820,11 +820,10 @@ static int help(void) {
                "  list-timezones           Show known time zones\n"
                "  set-local-rtc BOOL       Control whether RTC is in local time\n"
                "  set-ntp BOOL             Enable or disable network time synchronization\n"
-               "\n"
-               "systemd-timesyncd Commands:\n"
+               "\nsystemd-timesyncd Commands:\n"
                "  timesync-status          Show status of systemd-timesyncd\n"
                "  show-timesync            Show properties of systemd-timesyncd\n"
-               "\nOptions\n"
+               "\nOptions:\n"
                "  -h --help                Show this help message\n"
                "     --version             Show package version\n"
                "     --no-pager            Do not pipe output into a pager\n"
@@ -837,8 +836,8 @@ static int help(void) {
                "  -a --all                 Show all properties, including empty ones\n"
                "     --value               When showing properties, only print the value\n"
                "\nSee the %s for details.\n"
-               , ansi_highlight()
                , program_invocation_short_name
+               , ansi_highlight()
                , ansi_normal()
                , link
         );