Skip to content

Commit 353b2ba

Browse files
poetteringkeszybz
poettering
authored and
keszybz
committed
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.
1 parent ce0d4c4 commit 353b2ba

File tree

21 files changed

+192
-136
lines changed

21 files changed

+192
-136
lines changed

‎src/activate/activate.c‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -332,9 +332,9 @@ static int help(void) {
332332
if (r < 0)
333333
return log_oom();
334334

335-
printf("%s [OPTIONS...]\n\n"
336-
"Listen on sockets and launch child on connection.\n\n"
337-
"Options:\n"
335+
printf("%s [OPTIONS...]\n"
336+
"\n%sListen on sockets and launch child on connection.%s\n"
337+
"\nOptions:\n"
338338
" -h --help Show this help and exit\n"
339339
" --version Print version string and exit\n"
340340
" -l --listen=ADDR Listen for raw connections at ADDR\n"
@@ -347,6 +347,7 @@ static int help(void) {
347347
"\nNote: file descriptors from sd_listen_fds() will be passed through.\n"
348348
"\nSee the %s for details.\n"
349349
, program_invocation_short_name
350+
, ansi_highlight(), ansi_normal()
350351
, link
351352
);
352353

‎src/analyze/analyze.c‎

Lines changed: 23 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2243,26 +2243,8 @@ static int help(int argc, char *argv[], void *userdata) {
22432243
if (r < 0)
22442244
return log_oom();
22452245

2246-
printf("%s [OPTIONS...] {COMMAND} ...\n\n"
2247-
"Profile systemd, show unit dependencies, check unit files.\n\n"
2248-
" -h --help Show this help\n"
2249-
" --version Show package version\n"
2250-
" --no-pager Do not pipe output into a pager\n"
2251-
" --system Operate on system systemd instance\n"
2252-
" --user Operate on user systemd instance\n"
2253-
" --global Operate on global user configuration\n"
2254-
" -H --host=[USER@]HOST Operate on remote host\n"
2255-
" -M --machine=CONTAINER Operate on local container\n"
2256-
" --order Show only order in the graph\n"
2257-
" --require Show only requirement in the graph\n"
2258-
" --from-pattern=GLOB Show only origins in the graph\n"
2259-
" --to-pattern=GLOB Show only destinations in the graph\n"
2260-
" --fuzz=SECONDS Also print services which finished SECONDS earlier\n"
2261-
" than the latest in the branch\n"
2262-
" --man[=BOOL] Do [not] check for existence of man pages\n"
2263-
" --generators[=BOOL] Do [not] run unit generators (requires privileges)\n"
2264-
" --iterations=N Show the specified number of iterations\n"
2265-
" --base-time=TIMESTAMP Calculate calendar times relative to specified time\n"
2246+
printf("%s [OPTIONS...] COMMAND ...\n\n"
2247+
"%sProfile systemd, show unit dependencies, check unit files.%s\n"
22662248
"\nCommands:\n"
22672249
" time Print time spent in the kernel\n"
22682250
" 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) {
22842266
" timestamp TIMESTAMP... Validate a timestamp\n"
22852267
" timespan SPAN... Validate a time span\n"
22862268
" security [UNIT...] Analyze security of unit\n"
2269+
"\nOptions:\n"
2270+
" -h --help Show this help\n"
2271+
" --version Show package version\n"
2272+
" --no-pager Do not pipe output into a pager\n"
2273+
" --system Operate on system systemd instance\n"
2274+
" --user Operate on user systemd instance\n"
2275+
" --global Operate on global user configuration\n"
2276+
" -H --host=[USER@]HOST Operate on remote host\n"
2277+
" -M --machine=CONTAINER Operate on local container\n"
2278+
" --order Show only order in the graph\n"
2279+
" --require Show only requirement in the graph\n"
2280+
" --from-pattern=GLOB Show only origins in the graph\n"
2281+
" --to-pattern=GLOB Show only destinations in the graph\n"
2282+
" --fuzz=SECONDS Also print services which finished SECONDS earlier\n"
2283+
" than the latest in the branch\n"
2284+
" --man[=BOOL] Do [not] check for existence of man pages\n"
2285+
" --generators[=BOOL] Do [not] run unit generators (requires privileges)\n"
2286+
" --iterations=N Show the specified number of iterations\n"
2287+
" --base-time=TIMESTAMP Calculate calendar times relative to specified time\n"
22872288
"\nSee the %s for details.\n"
22882289
, program_invocation_short_name
2290+
, ansi_highlight()
2291+
, ansi_normal()
22892292
, dot_link
22902293
, link
22912294
);

‎src/boot/bless-boot.c‎

Lines changed: 21 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313
#include "main-func.h"
1414
#include "parse-util.h"
1515
#include "path-util.h"
16+
#include "pretty-print.h"
17+
#include "terminal-util.h"
1618
#include "util.h"
1719
#include "verbs.h"
1820
#include "virt.h"
@@ -22,19 +24,29 @@ static char **arg_path = NULL;
2224
STATIC_DESTRUCTOR_REGISTER(arg_path, strv_freep);
2325

2426
static int help(int argc, char *argv[], void *userdata) {
27+
_cleanup_free_ char *link = NULL;
28+
int r;
29+
30+
r = terminal_urlify_man("systemd-bless-boot.service", "8", &link);
31+
if (r < 0)
32+
return log_oom();
2533

26-
printf("%s [COMMAND] [OPTIONS...]\n"
27-
"\n"
28-
"Mark the boot process as good or bad.\n\n"
34+
printf("%s [OPTIONS...] COMMAND\n"
35+
"\n%sMark the boot process as good or bad.%s\n"
36+
"\nCommands:\n"
37+
" good Mark this boot as good\n"
38+
" bad Mark this boot as bad\n"
39+
" indeterminate Undo any marking as good or bad\n"
40+
"\nOptions:\n"
2941
" -h --help Show this help\n"
3042
" --version Print version\n"
3143
" --path=PATH Path to the $BOOT partition (may be used multiple times)\n"
32-
"\n"
33-
"Commands:\n"
34-
" good Mark this boot as good\n"
35-
" bad Mark this boot as bad\n"
36-
" indeterminate Undo any marking as good or bad\n",
37-
program_invocation_short_name);
44+
"\nSee the %s for details.\n"
45+
, program_invocation_short_name
46+
, ansi_highlight()
47+
, ansi_normal()
48+
, link
49+
);
3850

3951
return 0;
4052
}

‎src/boot/boot-check-no-failures.c‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,28 @@
1111
#include "bus-error.h"
1212
#include "log.h"
1313
#include "main-func.h"
14+
#include "pretty-print.h"
15+
#include "terminal-util.h"
1416
#include "util.h"
1517

1618
static int help(void) {
19+
_cleanup_free_ char *link = NULL;
20+
int r;
21+
22+
r = terminal_urlify_man("systemd-boot-check-no-failures.service", "8", &link);
23+
if (r < 0)
24+
return log_oom();
1725

18-
printf("%s [COMMAND] [OPTIONS...]\n"
19-
"\n"
20-
"Verify system operational state.\n\n"
26+
printf("%s [OPTIONS...]\n"
27+
"\n%sVerify system operational state.%s\n\n"
2128
" -h --help Show this help\n"
22-
" --version Print version\n",
23-
program_invocation_short_name);
29+
" --version Print version\n"
30+
"\nSee the %s for details.\n"
31+
, program_invocation_short_name
32+
, ansi_highlight()
33+
, ansi_normal()
34+
, link
35+
);
2436

2537
return 0;
2638
}

‎src/boot/bootctl.c‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1032,8 +1032,8 @@ static int help(int argc, char *argv[], void *userdata) {
10321032
if (r < 0)
10331033
return log_oom();
10341034

1035-
printf("%s [COMMAND] [OPTIONS...]\n\n"
1036-
"Install, update or remove the systemd-boot EFI boot manager.\n"
1035+
printf("%s [OPTIONS...] COMMAND ...\n"
1036+
"\n%sInstall, update or remove the systemd-boot EFI boot manager.%s\n"
10371037
"\nBoot Loader Commands:\n"
10381038
" status Show status of installed systemd-boot and EFI variables\n"
10391039
" install Install systemd-boot to the ESP and EFI variables\n"
@@ -1046,6 +1046,7 @@ static int help(int argc, char *argv[], void *userdata) {
10461046
" list List boot loader entries\n"
10471047
" set-default ID Set default boot loader entry\n"
10481048
" set-oneshot ID Set default boot loader entry, for next boot only\n"
1049+
"\nOptions:\n"
10491050
" -h --help Show this help\n"
10501051
" --version Print version\n"
10511052
" --esp-path=PATH Path to the EFI System Partition (ESP)\n"
@@ -1056,6 +1057,8 @@ static int help(int argc, char *argv[], void *userdata) {
10561057
" --no-pager Do not pipe output into a pager\n"
10571058
"\nSee the %s for details.\n"
10581059
, program_invocation_short_name
1060+
, ansi_highlight()
1061+
, ansi_normal()
10591062
, link);
10601063

10611064
return 0;

‎src/busctl/busctl.c‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2228,9 +2228,9 @@ static int help(void) {
22282228
if (r < 0)
22292229
return log_oom();
22302230

2231-
printf("%s%s [OPTIONS...] {COMMAND} ...\n\n"
2232-
"Introspect the bus.%s\n\n"
2233-
"Commands:\n"
2231+
printf("%s [OPTIONS...] COMMAND ...\n\n"
2232+
"%sIntrospect the D-Bus IPC bus.%s\n"
2233+
"\nCommands:\n"
22342234
" list List bus names\n"
22352235
" status [SERVICE] Show bus service, process or bus owner credentials\n"
22362236
" monitor [SERVICE...] Show bus traffic\n"
@@ -2277,8 +2277,8 @@ static int help(void) {
22772277
" system\n"
22782278
" --destination=SERVICE Destination service of a signal\n"
22792279
"\nSee the %s for details.\n"
2280-
, ansi_highlight()
22812280
, program_invocation_short_name
2281+
, ansi_highlight()
22822282
, ansi_normal()
22832283
, link
22842284
);

‎src/coredump/coredumpctl.c‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -145,14 +145,14 @@ static int help(void) {
145145
if (r < 0)
146146
return log_oom();
147147

148-
printf("%s%s [OPTIONS...]\n\n"
149-
"List or retrieve coredumps from the journal.%s\n"
148+
printf("%s [OPTIONS...] COMMAND ...\n\n"
149+
"%sList or retrieve coredumps from the journal.%s\n"
150150
"\nCommands:\n"
151151
" list [MATCHES...] List available coredumps (default)\n"
152152
" info [MATCHES...] Show detailed information about one or more coredumps\n"
153153
" dump [MATCHES...] Print first matching coredump to stdout\n"
154154
" debug [MATCHES...] Start a debugger for the first matching coredump\n"
155-
"\nFlags:\n"
155+
"\nOptions:\n"
156156
" -h --help Show this help\n"
157157
" --version Print version string\n"
158158
" --no-pager Do not pipe output into a pager\n"
@@ -167,8 +167,8 @@ static int help(void) {
167167
" -D --directory=DIR Use journal files from directory\n\n"
168168
" -q --quiet Do not show info messages and privilege warning\n"
169169
"\nSee the %s for details.\n"
170-
, ansi_highlight()
171170
, program_invocation_short_name
171+
, ansi_highlight()
172172
, ansi_normal()
173173
, link
174174
);

‎src/hostname/hostnamectl.c‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -310,8 +310,8 @@ static int help(void) {
310310
if (r < 0)
311311
return log_oom();
312312

313-
printf("%s%s [OPTIONS...] COMMAND ...\n\n"
314-
"Query or change system hostname.%s\n"
313+
printf("%s [OPTIONS...] COMMAND ...\n\n"
314+
"%sQuery or change system hostname.%s\n"
315315
"\nCommands:\n"
316316
" status Show current hostname settings\n"
317317
" set-hostname NAME Set system hostname\n"
@@ -329,8 +329,8 @@ static int help(void) {
329329
" --static Only set static hostname\n"
330330
" --pretty Only set pretty hostname\n"
331331
"\nSee the %s for details.\n"
332-
, ansi_highlight()
333332
, program_invocation_short_name
333+
, ansi_highlight()
334334
, ansi_normal()
335335
, link
336336
);

‎src/hwdb/hwdb.c‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
#include "main-func.h"
1010
#include "pretty-print.h"
1111
#include "selinux-util.h"
12+
#include "terminal-util.h"
1213
#include "util.h"
1314
#include "verbs.h"
1415

@@ -32,18 +33,21 @@ static int help(void) {
3233
if (r < 0)
3334
return log_oom();
3435

35-
printf("%s OPTIONS COMMAND\n\n"
36-
"Update or query the hardware database.\n\n"
36+
printf("%s [OPTIONS...] COMMAND ...\n\n"
37+
"%sUpdate or query the hardware database.%s\n"
38+
"\nCommands:\n"
39+
" update Update the hwdb database\n"
40+
" query MODALIAS Query database and print result\n"
41+
"\nOptions:\n"
3742
" -h --help Show this help\n"
3843
" --version Show package version\n"
3944
" -s --strict When updating, return non-zero exit value on any parsing error\n"
4045
" --usr Generate in " UDEVLIBEXECDIR " instead of /etc/udev\n"
4146
" -r --root=PATH Alternative root path in the filesystem\n\n"
42-
"Commands:\n"
43-
" update Update the hwdb database\n"
44-
" query MODALIAS Query database and print result\n"
4547
"\nSee the %s for details.\n"
4648
, program_invocation_short_name
49+
, ansi_highlight()
50+
, ansi_normal()
4751
, link
4852
);
4953

‎src/journal/cat.c‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
#include "pretty-print.h"
1717
#include "string-util.h"
1818
#include "syslog-util.h"
19+
#include "terminal-util.h"
1920
#include "util.h"
2021

2122
static const char *arg_identifier = NULL;
@@ -31,8 +32,8 @@ static int help(void) {
3132
if (r < 0)
3233
return log_oom();
3334

34-
printf("%s [OPTIONS...] {COMMAND} ...\n\n"
35-
"Execute process with stdout/stderr connected to the journal.\n\n"
35+
printf("%s [OPTIONS...] COMMAND ...\n"
36+
"\n%sExecute process with stdout/stderr connected to the journal.%s\n\n"
3637
" -h --help Show this help\n"
3738
" --version Show package version\n"
3839
" -t --identifier=STRING Set syslog identifier\n"
@@ -41,6 +42,7 @@ static int help(void) {
4142
" --level-prefix=BOOL Control whether level prefix shall be parsed\n"
4243
"\nSee the %s for details.\n"
4344
, program_invocation_short_name
45+
, ansi_highlight(), ansi_normal()
4446
, link
4547
);
4648

0 commit comments

Comments
 (0)