* [PATCH 0/6] consolidate help/version option descriptions
@ 2017-06-26 18:29 Ruediger Meier
2017-06-26 18:29 ` [PATCH 1/6] misc: revert to the old USAGE_HELP strings Ruediger Meier
` (6 more replies)
0 siblings, 7 replies; 18+ messages in thread
From: Ruediger Meier @ 2017-06-26 18:29 UTC (permalink / raw)
To: util-linux
From: Ruediger Meier <ruediger.meier@ga-group.nl>
Hope you will like it.
The final description strings (last patch) are just a
proposal. ALso maybe better macro names!?
This pull request is also on github:
https://github.com/karelzak/util-linux/pull/474
Ruediger Meier (6):
misc: revert to the old USAGE_HELP strings
misc: introduce PRINT_USAGE_HELP()
misc: consolidate all --help option descriptions
blockdev: improve --help and man page
login: add --help text
misc: update --help content again
Documentation/boilerplate.c | 3 +--
disk-utils/addpart.c | 3 +--
disk-utils/blockdev.8 | 9 +++++++--
disk-utils/blockdev.c | 34 +++++++++++++++++++++++-----------
disk-utils/cfdisk.c | 3 +--
disk-utils/delpart.c | 3 +--
disk-utils/fdformat.c | 3 +--
disk-utils/fdisk.c | 3 +--
disk-utils/fsck.c | 4 ++--
disk-utils/fsck.cramfs.c | 5 ++---
disk-utils/fsck.minix.c | 3 +--
disk-utils/isosize.c | 3 +--
disk-utils/mkfs.bfs.c | 5 ++---
disk-utils/mkfs.c | 5 +----
disk-utils/mkfs.cramfs.c | 3 +--
disk-utils/mkfs.minix.c | 3 +--
disk-utils/mkswap.c | 5 +++--
disk-utils/partx.c | 3 +--
disk-utils/raw.c | 3 +--
disk-utils/resizepart.c | 3 +--
disk-utils/sfdisk.c | 4 ++--
disk-utils/swaplabel.c | 3 +--
include/c.h | 14 ++++++++++++--
login-utils/chfn.c | 4 ++--
login-utils/chsh.c | 4 ++--
login-utils/last.c | 3 +--
login-utils/login.c | 8 ++++++++
login-utils/lslogins.c | 3 +--
login-utils/newgrp.c | 3 +--
login-utils/nologin.c | 3 +--
login-utils/su-common.c | 3 +--
login-utils/sulogin.c | 3 +--
login-utils/utmpdump.c | 3 +--
login-utils/vipw.c | 3 +--
misc-utils/blkid.c | 3 +--
misc-utils/cal.c | 3 +--
misc-utils/fincore.c | 3 +--
misc-utils/findfs.c | 3 +--
misc-utils/findmnt.c | 4 +---
misc-utils/getopt.c | 3 +--
misc-utils/kill.c | 3 +--
misc-utils/logger.c | 3 +--
misc-utils/look.c | 3 +--
misc-utils/lsblk.c | 3 +--
misc-utils/lslocks.c | 3 +--
misc-utils/mcookie.c | 3 +--
misc-utils/namei.c | 4 ++--
misc-utils/rename.c | 3 +--
misc-utils/uuidd.c | 3 +--
misc-utils/uuidgen.c | 3 +--
misc-utils/uuidparse.c | 3 +--
misc-utils/whereis.c | 3 +--
misc-utils/wipefs.c | 5 ++---
schedutils/chrt.c | 3 +--
schedutils/ionice.c | 3 +--
schedutils/taskset.c | 6 +++---
sys-utils/blkdiscard.c | 3 +--
sys-utils/blkzone.c | 3 +--
sys-utils/chcpu.c | 22 ++++++++++++----------
sys-utils/chmem.c | 3 +--
sys-utils/ctrlaltdel.c | 3 +--
sys-utils/dmesg.c | 5 ++---
sys-utils/eject.c | 3 +--
sys-utils/fallocate.c | 3 +--
sys-utils/flock.c | 3 +--
sys-utils/fsfreeze.c | 3 +--
sys-utils/fstrim.c | 3 +--
sys-utils/hwclock.c | 3 +--
sys-utils/ipcmk.c | 3 +--
sys-utils/ipcrm.c | 3 +--
sys-utils/ipcs.c | 3 +--
sys-utils/ldattach.c | 3 +--
sys-utils/losetup.c | 3 +--
sys-utils/lscpu.c | 3 +--
sys-utils/lsipc.c | 3 +--
sys-utils/lsmem.c | 3 +--
sys-utils/lsns.c | 3 +--
sys-utils/mount.c | 3 +--
sys-utils/mountpoint.c | 3 +--
sys-utils/nsenter.c | 3 +--
sys-utils/pivot_root.c | 3 +--
sys-utils/prlimit.c | 4 ++--
sys-utils/readprofile.c | 3 +--
sys-utils/renice.c | 3 +--
sys-utils/rtcwake.c | 3 +--
sys-utils/setarch.c | 3 +--
sys-utils/setpriv.c | 3 +--
sys-utils/setsid.c | 3 +--
sys-utils/swapoff.c | 3 +--
sys-utils/swapon.c | 3 +--
sys-utils/switch_root.c | 3 +--
sys-utils/tunelp.c | 3 +--
sys-utils/umount.c | 3 +--
sys-utils/unshare.c | 3 +--
sys-utils/wdctl.c | 3 +--
sys-utils/zramctl.c | 3 +--
term-utils/agetty.c | 4 ++--
term-utils/mesg.c | 3 +--
term-utils/script.c | 4 ++--
term-utils/scriptreplay.c | 4 ++--
term-utils/setterm.c | 5 +++--
term-utils/wall.c | 3 +--
term-utils/write.c | 3 +--
text-utils/col.c | 6 ++++--
text-utils/colcrt.c | 3 +--
text-utils/colrm.c | 3 +--
text-utils/column.c | 3 +--
text-utils/hexdump.c | 3 +--
text-utils/line.c | 3 +--
text-utils/more.c | 4 ++--
text-utils/pg.c | 3 +--
text-utils/rev.c | 3 +--
text-utils/ul.c | 3 +--
113 files changed, 193 insertions(+), 249 deletions(-)
--
2.12.3
^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH 1/6] misc: revert to the old USAGE_HELP strings
2017-06-26 18:29 [PATCH 0/6] consolidate help/version option descriptions Ruediger Meier
@ 2017-06-26 18:29 ` Ruediger Meier
2017-06-26 18:29 ` [PATCH 2/6] misc: introduce PRINT_USAGE_HELP() Ruediger Meier
` (5 subsequent siblings)
6 siblings, 0 replies; 18+ messages in thread
From: Ruediger Meier @ 2017-06-26 18:29 UTC (permalink / raw)
To: util-linux
From: Ruediger Meier <ruediger.meier@ga-group.nl>
This reverts the include/c.h part of cc7cb070.
As discussed on ml. Our current strings are imported from
coreutils and not too bad. Also the old strings are still
hardcoded at many places.
So let's revert the change, then consolidate these strings
really everywhere and then think again whether and how we
should change them.
Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
---
include/c.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/include/c.h b/include/c.h
index 3e5b87d3f..fe46b8c2d 100644
--- a/include/c.h
+++ b/include/c.h
@@ -315,8 +315,8 @@ static inline int xusleep(useconds_t usec)
#define USAGE_COMMANDS _("\nCommands:\n")
#define USAGE_COLUMNS _("\nAvailable output columns:\n")
#define USAGE_SEPARATOR "\n"
-#define USAGE_HELP _(" -h, --help display help information and exit\n")
-#define USAGE_VERSION _(" -V, --version display version information and exit\n")
+#define USAGE_HELP _(" -h, --help display this help and exit\n")
+#define USAGE_VERSION _(" -V, --version output version information and exit\n")
#define USAGE_MAN_TAIL(_man) _("\nFor more details see %s.\n"), _man
#define UTIL_LINUX_VERSION _("%s from %s\n"), program_invocation_short_name, PACKAGE_STRING
--
2.12.3
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 2/6] misc: introduce PRINT_USAGE_HELP()
2017-06-26 18:29 [PATCH 0/6] consolidate help/version option descriptions Ruediger Meier
2017-06-26 18:29 ` [PATCH 1/6] misc: revert to the old USAGE_HELP strings Ruediger Meier
@ 2017-06-26 18:29 ` Ruediger Meier
2017-06-27 9:46 ` Karel Zak
2017-06-26 18:29 ` [PATCH 3/6] misc: consolidate all --help option descriptions Ruediger Meier
` (4 subsequent siblings)
6 siblings, 1 reply; 18+ messages in thread
From: Ruediger Meier @ 2017-06-26 18:29 UTC (permalink / raw)
To: util-linux
From: Ruediger Meier <ruediger.meier@ga-group.nl>
Consolidate --help and --version descriptions. We are
now able to align them to the other options.
We changed include/c.h. The rest of this patch was
generated by sed, plus manually setting the right
alignment numbers. We do not change anything but
white spaces in the --help output.
Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
---
Documentation/boilerplate.c | 3 +--
disk-utils/addpart.c | 3 +--
disk-utils/cfdisk.c | 3 +--
disk-utils/delpart.c | 3 +--
disk-utils/fdformat.c | 3 +--
disk-utils/fdisk.c | 3 +--
disk-utils/fsck.cramfs.c | 3 +--
disk-utils/fsck.minix.c | 3 +--
disk-utils/isosize.c | 3 +--
disk-utils/mkfs.cramfs.c | 3 +--
disk-utils/mkfs.minix.c | 3 +--
disk-utils/partx.c | 3 +--
disk-utils/raw.c | 3 +--
disk-utils/resizepart.c | 3 +--
disk-utils/sfdisk.c | 4 ++--
disk-utils/swaplabel.c | 3 +--
include/c.h | 14 ++++++++++++--
login-utils/last.c | 3 +--
login-utils/lslogins.c | 3 +--
login-utils/newgrp.c | 3 +--
login-utils/nologin.c | 3 +--
login-utils/su-common.c | 3 +--
login-utils/sulogin.c | 3 +--
login-utils/utmpdump.c | 3 +--
login-utils/vipw.c | 3 +--
misc-utils/blkid.c | 3 +--
misc-utils/cal.c | 3 +--
misc-utils/fincore.c | 3 +--
misc-utils/findfs.c | 3 +--
misc-utils/findmnt.c | 3 +--
misc-utils/getopt.c | 3 +--
misc-utils/kill.c | 3 +--
misc-utils/logger.c | 3 +--
misc-utils/look.c | 3 +--
misc-utils/lsblk.c | 3 +--
misc-utils/lslocks.c | 3 +--
misc-utils/mcookie.c | 3 +--
misc-utils/rename.c | 3 +--
misc-utils/uuidd.c | 3 +--
misc-utils/uuidgen.c | 3 +--
misc-utils/uuidparse.c | 3 +--
misc-utils/whereis.c | 3 +--
schedutils/chrt.c | 3 +--
schedutils/ionice.c | 3 +--
schedutils/taskset.c | 1 -
sys-utils/blkdiscard.c | 3 +--
sys-utils/blkzone.c | 3 +--
sys-utils/chmem.c | 3 +--
sys-utils/ctrlaltdel.c | 3 +--
sys-utils/dmesg.c | 3 +--
sys-utils/eject.c | 3 +--
sys-utils/fallocate.c | 3 +--
sys-utils/flock.c | 3 +--
sys-utils/fsfreeze.c | 3 +--
sys-utils/fstrim.c | 3 +--
sys-utils/hwclock.c | 3 +--
sys-utils/ipcmk.c | 3 +--
sys-utils/ipcrm.c | 3 +--
sys-utils/ipcs.c | 3 +--
sys-utils/ldattach.c | 3 +--
sys-utils/losetup.c | 3 +--
sys-utils/lscpu.c | 3 +--
sys-utils/lsipc.c | 3 +--
sys-utils/lsmem.c | 3 +--
sys-utils/lsns.c | 3 +--
sys-utils/mount.c | 3 +--
sys-utils/mountpoint.c | 3 +--
sys-utils/nsenter.c | 3 +--
sys-utils/pivot_root.c | 3 +--
sys-utils/readprofile.c | 3 +--
sys-utils/renice.c | 3 +--
sys-utils/rtcwake.c | 3 +--
sys-utils/setarch.c | 3 +--
sys-utils/setpriv.c | 3 +--
sys-utils/setsid.c | 3 +--
sys-utils/swapoff.c | 3 +--
sys-utils/swapon.c | 3 +--
sys-utils/switch_root.c | 3 +--
sys-utils/tunelp.c | 3 +--
sys-utils/umount.c | 3 +--
sys-utils/unshare.c | 3 +--
sys-utils/wdctl.c | 3 +--
sys-utils/zramctl.c | 3 +--
term-utils/mesg.c | 3 +--
term-utils/wall.c | 3 +--
term-utils/write.c | 3 +--
text-utils/colcrt.c | 3 +--
text-utils/colrm.c | 3 +--
text-utils/column.c | 3 +--
text-utils/hexdump.c | 3 +--
text-utils/line.c | 3 +--
text-utils/pg.c | 3 +--
text-utils/rev.c | 3 +--
text-utils/ul.c | 3 +--
94 files changed, 105 insertions(+), 187 deletions(-)
diff --git a/Documentation/boilerplate.c b/Documentation/boilerplate.c
index d0c163d8c..c9d110dd7 100644
--- a/Documentation/boilerplate.c
+++ b/Documentation/boilerplate.c
@@ -56,8 +56,7 @@ static void __attribute__((__noreturn__)) usage(void)
" consecutive lines are intended by two spaces\n"), out);
fputs(_(" -f, --foobar next option description resets indent\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25); /* char offset to align option descriptions */
fprintf(out, USAGE_MAN_TAIL("fixme-command-name(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/disk-utils/addpart.c b/disk-utils/addpart.c
index 07f4ca9a1..4393b1d05 100644
--- a/disk-utils/addpart.c
+++ b/disk-utils/addpart.c
@@ -19,8 +19,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Tell the kernel about the existence of a specified partition.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("addpart(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/disk-utils/cfdisk.c b/disk-utils/cfdisk.c
index e17bc9167..a74611f34 100644
--- a/disk-utils/cfdisk.c
+++ b/disk-utils/cfdisk.c
@@ -2559,8 +2559,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -z, --zero start with zeroed partition table\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
fprintf(out, USAGE_MAN_TAIL("cfdisk(8)"));
exit(EXIT_SUCCESS);
diff --git a/disk-utils/delpart.c b/disk-utils/delpart.c
index 7f347c886..1c9f56f82 100644
--- a/disk-utils/delpart.c
+++ b/disk-utils/delpart.c
@@ -19,8 +19,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Tell the kernel to forget about a specified partition.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("delpart(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/disk-utils/fdformat.c b/disk-utils/fdformat.c
index 4b5ed5690..1a5323755 100644
--- a/disk-utils/fdformat.c
+++ b/disk-utils/fdformat.c
@@ -156,8 +156,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -n, --no-verify disable the verification after the format\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(19);
fprintf(out, USAGE_MAN_TAIL("fdformat(8)"));
exit(EXIT_SUCCESS);
diff --git a/disk-utils/fdisk.c b/disk-utils/fdisk.c
index afd968076..9e98dd436 100644
--- a/disk-utils/fdisk.c
+++ b/disk-utils/fdisk.c
@@ -785,8 +785,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -S, --sectors <number> specify the number of sectors per track\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(31);
list_available_columns(out);
diff --git a/disk-utils/fsck.cramfs.c b/disk-utils/fsck.cramfs.c
index ff056c869..df13d2bb4 100644
--- a/disk-utils/fsck.cramfs.c
+++ b/disk-utils/fsck.cramfs.c
@@ -120,8 +120,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -b, --blocksize <size> use this blocksize, defaults to page size\n"), out);
fputs(_(" --extract[=<dir>] test uncompression, optionally extract into <dir>\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fputs(USAGE_SEPARATOR, out);
exit(FSCK_EX_OK);
diff --git a/disk-utils/fsck.minix.c b/disk-utils/fsck.minix.c
index 13b12926c..f39266b89 100644
--- a/disk-utils/fsck.minix.c
+++ b/disk-utils/fsck.minix.c
@@ -192,8 +192,7 @@ usage(void) {
fputs(_(" -m, --uncleared activate mode not cleared warnings\n"), out);
fputs(_(" -f, --force force check\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(18);
fprintf(out, USAGE_MAN_TAIL("fsck.minix(8)"));
exit(FSCK_EX_OK);
}
diff --git a/disk-utils/isosize.c b/disk-utils/isosize.c
index ed43c9d70..c763a1888 100644
--- a/disk-utils/isosize.c
+++ b/disk-utils/isosize.c
@@ -141,8 +141,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -d, --divisor=<number> divide the amount of bytes by <number>\n"), out);
fputs(_(" -x, --sectors show sector count and size\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fprintf(out, USAGE_MAN_TAIL("isosize(8)"));
exit(EXIT_SUCCESS);
diff --git a/disk-utils/mkfs.cramfs.c b/disk-utils/mkfs.cramfs.c
index 74664a811..ff8199d85 100644
--- a/disk-utils/mkfs.cramfs.c
+++ b/disk-utils/mkfs.cramfs.c
@@ -144,8 +144,7 @@ static void __attribute__((__noreturn__)) usage(void)
program_invocation_short_name, PAD_SIZE);
fputs(USAGE_SEPARATOR, stdout);
- fputs(USAGE_HELP, stdout);
- fputs(USAGE_VERSION, stdout);
+ PRINT_USAGE_HELP(16);
printf(USAGE_MAN_TAIL("mkfs.cramfs(8)"));
exit(MKFS_EX_OK);
}
diff --git a/disk-utils/mkfs.minix.c b/disk-utils/mkfs.minix.c
index 39e159f7a..f67ce39ed 100644
--- a/disk-utils/mkfs.minix.c
+++ b/disk-utils/mkfs.minix.c
@@ -145,8 +145,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -c, --check check the device for bad blocks\n"), out);
fputs(_(" -l, --badblocks <file> list of bad blocks from file\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fprintf(out, USAGE_MAN_TAIL("mkfs.minix(8)"));
exit(MKFS_EX_OK);
}
diff --git a/disk-utils/partx.c b/disk-utils/partx.c
index 9a868cd81..ae7a4e03d 100644
--- a/disk-utils/partx.c
+++ b/disk-utils/partx.c
@@ -773,8 +773,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose verbose mode\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(22);
fputs(USAGE_COLUMNS, out);
for (i = 0; i < NCOLS; i++)
diff --git a/disk-utils/raw.c b/disk-utils/raw.c
index c881d86ee..d303e65ca 100644
--- a/disk-utils/raw.c
+++ b/disk-utils/raw.c
@@ -59,8 +59,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(USAGE_OPTIONS, out);
fputs(_(" -q, --query set query mode\n"), out);
fputs(_(" -a, --all query all raw devices\n"), out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("raw(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/disk-utils/resizepart.c b/disk-utils/resizepart.c
index a234c8079..a283de07b 100644
--- a/disk-utils/resizepart.c
+++ b/disk-utils/resizepart.c
@@ -24,8 +24,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Tell the kernel about the new size of a partition.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("resizepart(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/disk-utils/sfdisk.c b/disk-utils/sfdisk.c
index 6f88780d7..0a6b992f2 100644
--- a/disk-utils/sfdisk.c
+++ b/disk-utils/sfdisk.c
@@ -1901,8 +1901,8 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -u, --unit S deprecated, only sector unit is supported\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(_(" -v, --version output version information and exit\n"), out);
+ printf( " -h, --help %s\n", USAGE_HELP_TXT);
+ printf( " -v, --version %s\n", USAGE_VERSION_TXT);
list_available_columns(out);
diff --git a/disk-utils/swaplabel.c b/disk-utils/swaplabel.c
index c8fede25e..922ed8f36 100644
--- a/disk-utils/swaplabel.c
+++ b/disk-utils/swaplabel.c
@@ -125,8 +125,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -L, --label <label> specify a new label\n"
" -U, --uuid <uuid> specify a new uuid\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(21);
fprintf(out, USAGE_MAN_TAIL("swaplabel(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/include/c.h b/include/c.h
index fe46b8c2d..ce5551535 100644
--- a/include/c.h
+++ b/include/c.h
@@ -315,8 +315,18 @@ static inline int xusleep(useconds_t usec)
#define USAGE_COMMANDS _("\nCommands:\n")
#define USAGE_COLUMNS _("\nAvailable output columns:\n")
#define USAGE_SEPARATOR "\n"
-#define USAGE_HELP _(" -h, --help display this help and exit\n")
-#define USAGE_VERSION _(" -V, --version output version information and exit\n")
+
+#define USAGE_HELP_TXT _("display this help and exit")
+#define USAGE_VERSION_TXT _("output version information and exit")
+
+#define PRINT_USAGE_HELP(marg_dsc) \
+ printf( \
+ "%-" #marg_dsc "s%s\n" \
+ "%-" #marg_dsc "s%s\n" \
+ , " -h, --help", USAGE_HELP_TXT \
+ , " -V, --version", USAGE_VERSION_TXT \
+ )
+
#define USAGE_MAN_TAIL(_man) _("\nFor more details see %s.\n"), _man
#define UTIL_LINUX_VERSION _("%s from %s\n"), program_invocation_short_name, PACKAGE_STRING
diff --git a/login-utils/last.c b/login-utils/last.c
index 9cf6eb377..c52667935 100644
--- a/login-utils/last.c
+++ b/login-utils/last.c
@@ -589,8 +589,7 @@ static void __attribute__((__noreturn__)) usage(const struct last_control *ctl)
" notime|short|full|iso\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(22);
fprintf(out, USAGE_MAN_TAIL("last(1)"));
exit(out == stderr ? EXIT_FAILURE : EXIT_SUCCESS);
diff --git a/login-utils/lslogins.c b/login-utils/lslogins.c
index c15b347f2..baccdf0a2 100644
--- a/login-utils/lslogins.c
+++ b/login-utils/lslogins.c
@@ -1253,8 +1253,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --wtmp-file <path> set an alternate path for wtmp\n"), out);
fputs(_(" --btmp-file <path> set an alternate path for btmp\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
fputs(USAGE_COLUMNS, out);
for (i = 0; i < ARRAY_SIZE(coldescs); i++)
diff --git a/login-utils/newgrp.c b/login-utils/newgrp.c
index 767ae4bcf..34e2a3016 100644
--- a/login-utils/newgrp.c
+++ b/login-utils/newgrp.c
@@ -176,8 +176,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Log in to a new group.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP,out);
- fputs(USAGE_VERSION,out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("newgrp(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/login-utils/nologin.c b/login-utils/nologin.c
index 00b4b8af8..93b7bfc0f 100644
--- a/login-utils/nologin.c
+++ b/login-utils/nologin.c
@@ -30,8 +30,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Politely refuse a login.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("nologin(8)"));
exit(EXIT_FAILURE);
diff --git a/login-utils/su-common.c b/login-utils/su-common.c
index d7b0a93dd..cea7abb21 100644
--- a/login-utils/su-common.c
+++ b/login-utils/su-common.c
@@ -709,8 +709,7 @@ usage(void)
fputs (_(" -s, --shell <shell> run <shell> if /etc/shells allows it\n"), stdout);
fputs(USAGE_SEPARATOR, stdout);
- fputs(USAGE_HELP, stdout);
- fputs(USAGE_VERSION, stdout);
+ PRINT_USAGE_HELP(33);
printf(USAGE_MAN_TAIL(su_mode == SU_MODE ? "su(1)" : "runuser(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/login-utils/sulogin.c b/login-utils/sulogin.c
index ac6a15c38..0956fde97 100644
--- a/login-utils/sulogin.c
+++ b/login-utils/sulogin.c
@@ -812,8 +812,7 @@ static void usage(void)
out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
fprintf(out, USAGE_MAN_TAIL("sulogin(8)"));
}
diff --git a/login-utils/utmpdump.c b/login-utils/utmpdump.c
index 5bcb4c35f..ee1a3ecc2 100644
--- a/login-utils/utmpdump.c
+++ b/login-utils/utmpdump.c
@@ -311,8 +311,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -f, --follow output appended data as the file grows\n"), out);
fputs(_(" -r, --reverse write back dumped data into utmp file\n"), out);
fputs(_(" -o, --output <file> write to file instead of standard output\n"), out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(22);
fprintf(out, USAGE_MAN_TAIL("utmpdump(1)"));
exit(EXIT_SUCCESS);
diff --git a/login-utils/vipw.c b/login-utils/vipw.c
index e3cca4906..31649bac8 100644
--- a/login-utils/vipw.c
+++ b/login-utils/vipw.c
@@ -306,8 +306,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Edit the password or group file.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("vipw(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/misc-utils/blkid.c b/misc-utils/blkid.c
index f4757e8c8..457c4fe3a 100644
--- a/misc-utils/blkid.c
+++ b/misc-utils/blkid.c
@@ -103,8 +103,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_( " -n, --match-types <list> filter by filesystem type (e.g. -n vfat,ext3)\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(28);
fprintf(out, USAGE_MAN_TAIL("blkid(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/misc-utils/cal.c b/misc-utils/cal.c
index f73cbbf30..87ad3ad68 100644
--- a/misc-utils/cal.c
+++ b/misc-utils/cal.c
@@ -1015,8 +1015,7 @@ static void __attribute__((__noreturn__)) usage(void)
" %s\n", USAGE_COLORS_DEFAULT);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(23);
fprintf(out, USAGE_MAN_TAIL("cal(1)"));
exit(EXIT_SUCCESS);
diff --git a/misc-utils/fincore.c b/misc-utils/fincore.c
index f1b9fa758..20488d5b1 100644
--- a/misc-utils/fincore.c
+++ b/misc-utils/fincore.c
@@ -274,8 +274,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -r, --raw use raw output format\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(23);
fprintf(out, USAGE_COLUMNS);
diff --git a/misc-utils/findfs.c b/misc-utils/findfs.c
index c01dc1d53..beb708399 100644
--- a/misc-utils/findfs.c
+++ b/misc-utils/findfs.c
@@ -33,8 +33,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Find a filesystem by label or UUID.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("findfs(8)"));
exit(FINDFS_SUCCESS);
}
diff --git a/misc-utils/findmnt.c b/misc-utils/findmnt.c
index 5394d1a60..b5e4d66d0 100644
--- a/misc-utils/findmnt.c
+++ b/misc-utils/findmnt.c
@@ -1246,8 +1246,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputc('\n', out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fputs(USAGE_COLUMNS, out);
for (i = 0; i < ARRAY_SIZE(infos); i++)
diff --git a/misc-utils/getopt.c b/misc-utils/getopt.c
index 87d088ed5..5348ee62b 100644
--- a/misc-utils/getopt.c
+++ b/misc-utils/getopt.c
@@ -346,8 +346,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -T, --test test for getopt(1) version\n"), stdout);
fputs(_(" -u, --unquoted do not quote the output\n"), stdout);
fputs(USAGE_SEPARATOR, stdout);
- fputs(USAGE_HELP, stdout);
- fputs(USAGE_VERSION, stdout);
+ PRINT_USAGE_HELP(31);
printf(USAGE_MAN_TAIL("getopt(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/misc-utils/kill.c b/misc-utils/kill.c
index ecee26c4e..d245049aa 100644
--- a/misc-utils/kill.c
+++ b/misc-utils/kill.c
@@ -318,8 +318,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --verbose print pids that will be signaled\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fprintf(out, USAGE_MAN_TAIL("kill(1)"));
exit(EXIT_SUCCESS);
diff --git a/misc-utils/logger.c b/misc-utils/logger.c
index 0ae5c61d0..6d0d2ca01 100644
--- a/misc-utils/logger.c
+++ b/misc-utils/logger.c
@@ -1027,8 +1027,7 @@ static void __attribute__((__noreturn__)) usage(void)
#endif
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
fprintf(out, USAGE_MAN_TAIL("logger(1)"));
exit(EXIT_SUCCESS);
diff --git a/misc-utils/look.c b/misc-utils/look.c
index a0d898db1..2f54f8006 100644
--- a/misc-utils/look.c
+++ b/misc-utils/look.c
@@ -365,8 +365,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -t, --terminate <char> define the string-termination character\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
fprintf(out, USAGE_MAN_TAIL("look(1)"));
exit(EXIT_SUCCESS);
diff --git a/misc-utils/lsblk.c b/misc-utils/lsblk.c
index d997bc71e..dde4b2fc3 100644
--- a/misc-utils/lsblk.c
+++ b/misc-utils/lsblk.c
@@ -1658,8 +1658,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -t, --topology output info about topology\n"), out);
fputs(_(" -x, --sort <column> sort output by <column>\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(22);
fprintf(out, USAGE_COLUMNS);
diff --git a/misc-utils/lslocks.c b/misc-utils/lslocks.c
index 54440496a..541298ea1 100644
--- a/misc-utils/lslocks.c
+++ b/misc-utils/lslocks.c
@@ -507,8 +507,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -u, --notruncate don't truncate text in columns\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fputs(USAGE_COLUMNS, out);
diff --git a/misc-utils/mcookie.c b/misc-utils/mcookie.c
index 89b9a01eb..6237f175c 100644
--- a/misc-utils/mcookie.c
+++ b/misc-utils/mcookie.c
@@ -91,8 +91,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose explain what is being done\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(23);
fprintf(out, USAGE_MAN_TAIL("mcookie(1)"));
exit(EXIT_SUCCESS);
diff --git a/misc-utils/rename.c b/misc-utils/rename.c
index 48606d75e..2fb3aa998 100644
--- a/misc-utils/rename.c
+++ b/misc-utils/rename.c
@@ -144,8 +144,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -n, --no-act do not make any changes\n"), out);
fputs(_(" -o, --no-overwrite don't overwrite existing files\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(21);
fprintf(out, USAGE_MAN_TAIL("rename(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/misc-utils/uuidd.c b/misc-utils/uuidd.c
index faaa0c12f..71558e163 100644
--- a/misc-utils/uuidd.c
+++ b/misc-utils/uuidd.c
@@ -79,8 +79,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -d, --debug run in debugging mode\n"), out);
fputs(_(" -q, --quiet turn on quiet mode\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fprintf(out, USAGE_MAN_TAIL("uuidd(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/misc-utils/uuidgen.c b/misc-utils/uuidgen.c
index 77fda2fb3..0d18f5704 100644
--- a/misc-utils/uuidgen.c
+++ b/misc-utils/uuidgen.c
@@ -32,8 +32,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -r, --random generate random-based uuid\n"), out);
fputs(_(" -t, --time generate time-based uuid\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(18);
fprintf(out, USAGE_MAN_TAIL("uuidgen(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/misc-utils/uuidparse.c b/misc-utils/uuidparse.c
index 09a6b46a8..1c22c0cad 100644
--- a/misc-utils/uuidparse.c
+++ b/misc-utils/uuidparse.c
@@ -105,8 +105,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -r, --raw use the raw output format\n"), stdout);
fputs(USAGE_SEPARATOR, stdout);
- fputs(USAGE_HELP, stdout);
- fputs(USAGE_VERSION, stdout);
+ PRINT_USAGE_HELP(24);
fputs(USAGE_COLUMNS, stdout);
for (i = 0; i < ARRAY_SIZE(infos); i++)
diff --git a/misc-utils/whereis.c b/misc-utils/whereis.c
index 897a7a213..db786aae5 100644
--- a/misc-utils/whereis.c
+++ b/misc-utils/whereis.c
@@ -205,8 +205,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -l output effective lookup paths\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("whereis(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/schedutils/chrt.c b/schedutils/chrt.c
index d1abbe14e..24a2db3f1 100644
--- a/schedutils/chrt.c
+++ b/schedutils/chrt.c
@@ -165,8 +165,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose display status information\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(22);
fprintf(out, USAGE_MAN_TAIL("chrt(1)"));
exit(EXIT_SUCCESS);
diff --git a/schedutils/ionice.c b/schedutils/ionice.c
index 9d0648bca..77fa25b89 100644
--- a/schedutils/ionice.c
+++ b/schedutils/ionice.c
@@ -121,8 +121,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -u, --uid <uid>... act on already running processes owned by these users\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fprintf(out, USAGE_MAN_TAIL("ionice(1)"));
diff --git a/schedutils/taskset.c b/schedutils/taskset.c
index 9870040e7..c55b986fb 100644
--- a/schedutils/taskset.c
+++ b/schedutils/taskset.c
@@ -78,7 +78,6 @@ static void __attribute__((__noreturn__)) usage(void)
program_invocation_short_name);
fprintf(out, USAGE_MAN_TAIL("taskset(1)"));
-
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/blkdiscard.c b/sys-utils/blkdiscard.c
index e6a9dce5c..332b60750 100644
--- a/sys-utils/blkdiscard.c
+++ b/sys-utils/blkdiscard.c
@@ -96,8 +96,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose print aligned length and offset\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(21);
fprintf(out, USAGE_MAN_TAIL("blkdiscard(8)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/blkzone.c b/sys-utils/blkzone.c
index ee4902e45..588766965 100644
--- a/sys-utils/blkzone.c
+++ b/sys-utils/blkzone.c
@@ -311,8 +311,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -c, --count <number> maximum number of zones\n"), out);
fputs(_(" -v, --verbose display more details\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fprintf(out, USAGE_MAN_TAIL("blkzone(8)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/chmem.c b/sys-utils/chmem.c
index 7f7be6ab6..91ec73ca9 100644
--- a/sys-utils/chmem.c
+++ b/sys-utils/chmem.c
@@ -249,8 +249,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -b, --blocks use memory blocks\n"), out);
fputs(_(" -v, --verbose verbose output\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("chmem(8)"));
diff --git a/sys-utils/ctrlaltdel.c b/sys-utils/ctrlaltdel.c
index 98c8ed832..505c8cd29 100644
--- a/sys-utils/ctrlaltdel.c
+++ b/sys-utils/ctrlaltdel.c
@@ -31,8 +31,7 @@ static void __attribute__((__noreturn__)) usage(void)
fprintf(out, _("Set the function of the Ctrl-Alt-Del combination.\n"));
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION,out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("ctrlaltdel(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/dmesg.c b/sys-utils/dmesg.c
index cd5da90f4..eb47b9129 100644
--- a/sys-utils/dmesg.c
+++ b/sys-utils/dmesg.c
@@ -306,8 +306,7 @@ static void __attribute__((__noreturn__)) usage(void)
" [delta|reltime|ctime|notime|iso]\n"
"Suspending/resume will make ctime and iso timestamps inaccurate.\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(29);
fputs(_("\nSupported log facilities:\n"), out);
for (i = 0; i < ARRAY_SIZE(level_names); i++)
fprintf(out, " %7s - %s\n",
diff --git a/sys-utils/eject.c b/sys-utils/eject.c
index 296e5cba5..91f04dc0b 100644
--- a/sys-utils/eject.c
+++ b/sys-utils/eject.c
@@ -159,8 +159,7 @@ static void __attribute__((__noreturn__)) usage(void)
out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(29);
fputs(_("\nBy default tries -r, -s, -f, and -q in order until success.\n"), out);
fprintf(out, USAGE_MAN_TAIL("eject(1)"));
diff --git a/sys-utils/fallocate.c b/sys-utils/fallocate.c
index a2d212552..16233b249 100644
--- a/sys-utils/fallocate.c
+++ b/sys-utils/fallocate.c
@@ -101,8 +101,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose verbose mode\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(22);
fprintf(out, USAGE_MAN_TAIL("fallocate(1)"));
diff --git a/sys-utils/flock.c b/sys-utils/flock.c
index 5abe2def5..1091c41bf 100644
--- a/sys-utils/flock.c
+++ b/sys-utils/flock.c
@@ -70,8 +70,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_( " -F, --no-fork execute command without forking\n"), stdout);
fputs(_( " --verbose increase verbosity\n"), stdout);
fputs(USAGE_SEPARATOR, stdout);
- fputs(USAGE_HELP, stdout);
- fputs(USAGE_VERSION, stdout);
+ PRINT_USAGE_HELP(26);
printf(USAGE_MAN_TAIL("flock(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/fsfreeze.c b/sys-utils/fsfreeze.c
index 8b0d5d10e..7b1a1666d 100644
--- a/sys-utils/fsfreeze.c
+++ b/sys-utils/fsfreeze.c
@@ -47,8 +47,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -f, --freeze freeze the filesystem\n"), out);
fputs(_(" -u, --unfreeze unfreeze the filesystem\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(19);
fprintf(out, USAGE_MAN_TAIL("fsfreeze(8)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/fstrim.c b/sys-utils/fstrim.c
index 698f30a93..979d9857a 100644
--- a/sys-utils/fstrim.c
+++ b/sys-utils/fstrim.c
@@ -262,8 +262,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose print number of discarded bytes\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(21);
fprintf(out, USAGE_MAN_TAIL("fstrim(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index f3448a569..c6b85be29 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -1241,8 +1241,7 @@ usage(const struct hwclock_control *ctl)
fputs(_(" --test dry run; use -D to view what would have happened\n"), out);
fputs(_(" -D, --debug use debug mode\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(22);
fprintf(out, USAGE_MAN_TAIL("hwclock(8)"));
hwclock_exit(ctl, EXIT_SUCCESS);
}
diff --git a/sys-utils/ipcmk.c b/sys-utils/ipcmk.c
index c6d322cbf..8c10e7b55 100644
--- a/sys-utils/ipcmk.c
+++ b/sys-utils/ipcmk.c
@@ -76,8 +76,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -p, --mode <mode> permission for the resource (default is 0644)\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
fprintf(out, USAGE_MAN_TAIL("ipcmk(1)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/ipcrm.c b/sys-utils/ipcrm.c
index a60919d9b..88102e5fd 100644
--- a/sys-utils/ipcrm.c
+++ b/sys-utils/ipcrm.c
@@ -65,8 +65,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose explain what is being done\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(28);
fprintf(out, USAGE_MAN_TAIL("ipcrm(1)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/ipcs.c b/sys-utils/ipcs.c
index 943b09c4a..f3a216b5c 100644
--- a/sys-utils/ipcs.c
+++ b/sys-utils/ipcs.c
@@ -58,8 +58,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(USAGE_OPTIONS, out);
fputs(_(" -i, --id <id> print details on resource identified by <id>\n"), out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fputs(USAGE_SEPARATOR, out);
fputs(_("Resource options:\n"), out);
diff --git a/sys-utils/ldattach.c b/sys-utils/ldattach.c
index 9a3915b1c..e38e31eb2 100644
--- a/sys-utils/ldattach.c
+++ b/sys-utils/ldattach.c
@@ -213,8 +213,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -i, --iflag [-]<iflag> set input mode flag\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fputs(_("\nKnown <ldisc> names:\n"), out);
print_table(out, ld_discs);
diff --git a/sys-utils/losetup.c b/sys-utils/losetup.c
index 593d3b536..044109945 100644
--- a/sys-utils/losetup.c
+++ b/sys-utils/losetup.c
@@ -419,8 +419,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --raw use raw --list output format\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(31);
fputs(USAGE_COLUMNS, out);
for (i = 0; i < ARRAY_SIZE(infos); i++)
diff --git a/sys-utils/lscpu.c b/sys-utils/lscpu.c
index 2504da2e0..dc5f90fb4 100644
--- a/sys-utils/lscpu.c
+++ b/sys-utils/lscpu.c
@@ -2066,8 +2066,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -x, --hex print hexadecimal masks rather than lists of CPUs\n"), out);
fputs(_(" -y, --physical print physical instead of logical IDs\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fputs(USAGE_COLUMNS, out);
for (i = 0; i < ARRAY_SIZE(coldescs); i++)
diff --git a/sys-utils/lsipc.c b/sys-utils/lsipc.c
index 8ac50d67a..deee608ef 100644
--- a/sys-utils/lsipc.c
+++ b/sys-utils/lsipc.c
@@ -304,8 +304,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -t, --time show attach, detach and change times\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
fprintf(out, _("\nGeneric columns:\n"));
for (i = COLDESC_IDX_GEN_FIRST; i <= COLDESC_IDX_GEN_LAST; i++)
diff --git a/sys-utils/lsmem.c b/sys-utils/lsmem.c
index 4efd29632..630bdd861 100644
--- a/sys-utils/lsmem.c
+++ b/sys-utils/lsmem.c
@@ -386,8 +386,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --summary[=when] print summary information (never,always or only)\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(22);
fputs(USAGE_COLUMNS, out);
for (i = 0; i < ARRAY_SIZE(coldescs); i++)
diff --git a/sys-utils/lsns.c b/sys-utils/lsns.c
index 6cadd0ef5..443113071 100644
--- a/sys-utils/lsns.c
+++ b/sys-utils/lsns.c
@@ -627,8 +627,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -t, --type <name> namespace type (mnt, net, ipc, user, pid, uts, cgroup)\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fputs(USAGE_COLUMNS, out);
for (i = 0; i < ARRAY_SIZE(infos); i++)
diff --git a/sys-utils/mount.c b/sys-utils/mount.c
index b46634c7c..3d7d9c322 100644
--- a/sys-utils/mount.c
+++ b/sys-utils/mount.c
@@ -426,8 +426,7 @@ static void __attribute__((__noreturn__)) usage(void)
" -w, --rw, --read-write mount the filesystem read-write (default)\n"));
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fprintf(out, _(
"\nSource:\n"
diff --git a/sys-utils/mountpoint.c b/sys-utils/mountpoint.c
index d07077252..06b9bb90d 100644
--- a/sys-utils/mountpoint.c
+++ b/sys-utils/mountpoint.c
@@ -127,8 +127,7 @@ static void __attribute__((__noreturn__)) usage(void)
" -d, --fs-devno print maj:min device number of the filesystem\n"
" -x, --devno print maj:min device number of the block device\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(20);
fprintf(out, USAGE_MAN_TAIL("mountpoint(1)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/nsenter.c b/sys-utils/nsenter.c
index 204e6ce3b..10cd5eddb 100644
--- a/sys-utils/nsenter.c
+++ b/sys-utils/nsenter.c
@@ -97,8 +97,7 @@ static void __attribute__((__noreturn__)) usage(void)
#endif
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fprintf(out, USAGE_MAN_TAIL("nsenter(1)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/pivot_root.c b/sys-utils/pivot_root.c
index ee6fd3c19..e288936d5 100644
--- a/sys-utils/pivot_root.c
+++ b/sys-utils/pivot_root.c
@@ -38,8 +38,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Change the root filesystem.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("pivot_root(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/readprofile.c b/sys-utils/readprofile.c
index dc14c64f2..da2923874 100644
--- a/sys-utils/readprofile.c
+++ b/sys-utils/readprofile.c
@@ -122,8 +122,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -r, --reset reset all the counters (root only)\n"), out);
fputs(_(" -n, --no-auto disable byte order auto-detection\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(27);
fprintf(out, USAGE_MAN_TAIL("readprofile(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/renice.c b/sys-utils/renice.c
index a88f590fb..de1fb4bc5 100644
--- a/sys-utils/renice.c
+++ b/sys-utils/renice.c
@@ -73,8 +73,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -g, --pgrp <id> interpret argument as process group ID\n"), out);
fputs(_(" -u, --user <name>|<id> interpret argument as username or user ID\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fprintf(out, USAGE_MAN_TAIL("renice(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/rtcwake.c b/sys-utils/rtcwake.c
index 86c009536..519bd5e43 100644
--- a/sys-utils/rtcwake.c
+++ b/sys-utils/rtcwake.c
@@ -115,8 +115,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose verbose messages\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
printf(USAGE_MAN_TAIL("rtcwake(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/setarch.c b/sys-utils/setarch.c
index b14dbea40..40c9220f1 100644
--- a/sys-utils/setarch.c
+++ b/sys-utils/setarch.c
@@ -114,8 +114,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --list list settable architectures, and exit\n"), stdout);
fputs(USAGE_SEPARATOR, stdout);
- fputs(USAGE_HELP, stdout);
- fputs(USAGE_VERSION, stdout);
+ PRINT_USAGE_HELP(26);
printf(USAGE_MAN_TAIL("setarch(8)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/setpriv.c b/sys-utils/setpriv.c
index 310e6938d..ed36da042 100644
--- a/sys-utils/setpriv.c
+++ b/sys-utils/setpriv.c
@@ -122,8 +122,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --apparmor-profile <pr> set AppArmor profile\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fputs(USAGE_SEPARATOR, out);
fputs(_(" This tool can be dangerous. Read the manpage, and be careful.\n"), out);
fprintf(out, USAGE_MAN_TAIL("setpriv(1)"));
diff --git a/sys-utils/setsid.c b/sys-utils/setsid.c
index 891d8a6b7..fc49cd078 100644
--- a/sys-utils/setsid.c
+++ b/sys-utils/setsid.c
@@ -40,8 +40,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -c, --ctty set the controlling terminal to the current one\n"), out);
fputs(_(" -w, --wait wait program to exit, and use the same return\n"), out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("setsid(1)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/swapoff.c b/sys-utils/swapoff.c
index da2e268d7..5e97e8156 100644
--- a/sys-utils/swapoff.c
+++ b/sys-utils/swapoff.c
@@ -130,8 +130,7 @@ static void __attribute__((__noreturn__)) usage(void)
" -v, --verbose verbose mode\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fputs(_("\nThe <spec> parameter:\n" \
" -L <label> LABEL of device to be used\n" \
diff --git a/sys-utils/swapon.c b/sys-utils/swapon.c
index 5242b96f4..8cfc754e0 100644
--- a/sys-utils/swapon.c
+++ b/sys-utils/swapon.c
@@ -808,8 +808,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose verbose mode\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(26);
fputs(_("\nThe <spec> parameter:\n" \
" -L <label> synonym for LABEL=<label>\n"
diff --git a/sys-utils/switch_root.c b/sys-utils/switch_root.c
index dff334253..834b2a304 100644
--- a/sys-utils/switch_root.c
+++ b/sys-utils/switch_root.c
@@ -209,8 +209,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Switch to another filesystem as the root of the mount tree.\n"), output);
fputs(USAGE_OPTIONS, output);
- fputs(USAGE_HELP, output);
- fputs(USAGE_VERSION, output);
+ PRINT_USAGE_HELP(16);
fprintf(output, USAGE_MAN_TAIL("switch_root(8)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/tunelp.c b/sys-utils/tunelp.c
index 99da3f3f6..37f8fb56c 100644
--- a/sys-utils/tunelp.c
+++ b/sys-utils/tunelp.c
@@ -112,8 +112,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -r, --reset reset the port\n"), out);
fputs(_(" -q, --print-irq <on|off> display current irq setting\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(30);
fprintf(out, USAGE_MAN_TAIL("tunelp(8)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/umount.c b/sys-utils/umount.c
index 17d94be10..2751521b8 100644
--- a/sys-utils/umount.c
+++ b/sys-utils/umount.c
@@ -102,8 +102,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -v, --verbose say what is being done\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fprintf(out, USAGE_MAN_TAIL("umount(8)"));
exit(MNT_EX_SUCCESS);
diff --git a/sys-utils/unshare.c b/sys-utils/unshare.c
index d3973527b..8b62b560a 100644
--- a/sys-utils/unshare.c
+++ b/sys-utils/unshare.c
@@ -265,8 +265,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -s, --setgroups allow|deny control the setgroups syscall in user namespaces\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(27);
fprintf(out, USAGE_MAN_TAIL("unshare(1)"));
exit(EXIT_SUCCESS);
diff --git a/sys-utils/wdctl.c b/sys-utils/wdctl.c
index 28a24c1f8..662f9e44d 100644
--- a/sys-utils/wdctl.c
+++ b/sys-utils/wdctl.c
@@ -190,8 +190,7 @@ static void __attribute__((__noreturn__)) usage(void)
" -x, --flags-only print only flags table (same as -I -T)\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(24);
fputs(USAGE_SEPARATOR, out);
fprintf(out, _("The default device is %s.\n"), _PATH_WATCHDOG_DEV);
diff --git a/sys-utils/zramctl.c b/sys-utils/zramctl.c
index 948c58925..21441a5cb 100644
--- a/sys-utils/zramctl.c
+++ b/sys-utils/zramctl.c
@@ -543,8 +543,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -t, --streams <number> number of compression streams\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(27);
fputs(USAGE_COLUMNS, out);
for (i = 0; i < ARRAY_SIZE(infos); i++)
diff --git a/term-utils/mesg.c b/term-utils/mesg.c
index fe5218aa4..2c57d63d3 100644
--- a/term-utils/mesg.c
+++ b/term-utils/mesg.c
@@ -80,8 +80,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(USAGE_OPTIONS, out);
fputs(_(" -v, --verbose explain what is being done\n"), out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("mesg(1)"));
exit(EXIT_SUCCESS);
diff --git a/term-utils/wall.c b/term-utils/wall.c
index 803a02976..0194c4bd7 100644
--- a/term-utils/wall.c
+++ b/term-utils/wall.c
@@ -93,8 +93,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -n, --nobanner do not print banner, works only for root\n"), out);
fputs(_(" -t, --timeout <timeout> write timeout in seconds\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fprintf(out, USAGE_MAN_TAIL("wall(1)"));
exit(EXIT_SUCCESS);
diff --git a/term-utils/write.c b/term-utils/write.c
index a7b51809f..172c8a6fb 100644
--- a/term-utils/write.c
+++ b/term-utils/write.c
@@ -91,8 +91,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Send a message to another user.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("write(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/text-utils/colcrt.c b/text-utils/colcrt.c
index 375d0d6f0..bba6a574b 100644
--- a/text-utils/colcrt.c
+++ b/text-utils/colcrt.c
@@ -89,8 +89,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -2, --half-lines print all half-lines\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(25);
fprintf(out, USAGE_MAN_TAIL("colcrt(1)"));
diff --git a/text-utils/colrm.c b/text-utils/colrm.c
index ebebca0bf..a73604d47 100644
--- a/text-utils/colrm.c
+++ b/text-utils/colrm.c
@@ -65,8 +65,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Filter out the specified columns.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, _("%s reads from standard input and writes to standard output\n\n"),
program_invocation_short_name);
fprintf(out, USAGE_MAN_TAIL("colrm(1)"));
diff --git a/text-utils/column.c b/text-utils/column.c
index 7f956f721..7dfc73ce8 100644
--- a/text-utils/column.c
+++ b/text-utils/column.c
@@ -581,8 +581,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -x, --fillrows fill rows before columns\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(34);
fprintf(out, USAGE_MAN_TAIL("column(1)"));
exit(EXIT_SUCCESS);
diff --git a/text-utils/hexdump.c b/text-utils/hexdump.c
index 53d10a6d9..166a67502 100644
--- a/text-utils/hexdump.c
+++ b/text-utils/hexdump.c
@@ -174,8 +174,7 @@ void __attribute__((__noreturn__)) usage(void)
fputs(_(" -s, --skip <offset> skip offset bytes from the beginning\n"), out);
fputs(_(" -v, --no-squeezing output identical lines\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(27);
fprintf(out, USAGE_MAN_TAIL("hexdump(1)"));
exit(EXIT_SUCCESS);
diff --git a/text-utils/line.c b/text-utils/line.c
index 15d7d4adf..5ad4b093f 100644
--- a/text-utils/line.c
+++ b/text-utils/line.c
@@ -34,8 +34,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Read one line.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("line(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/text-utils/pg.c b/text-utils/pg.c
index ce5898dc3..97339b60a 100644
--- a/text-utils/pg.c
+++ b/text-utils/pg.c
@@ -247,8 +247,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" +/pattern/ start at the line containing pattern\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("pg(1)"));
exit(0);
diff --git a/text-utils/rev.c b/text-utils/rev.c
index 9a778e383..cd92ac9f5 100644
--- a/text-utils/rev.c
+++ b/text-utils/rev.c
@@ -81,8 +81,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Reverse lines characterwise.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(16);
fprintf(out, USAGE_MAN_TAIL("rev(1)"));
exit(EXIT_SUCCESS);
diff --git a/text-utils/ul.c b/text-utils/ul.c
index a2ad5ea42..af429739d 100644
--- a/text-utils/ul.c
+++ b/text-utils/ul.c
@@ -148,8 +148,7 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -t, -T, --terminal TERMINAL override the TERM environment variable\n"), out);
fputs(_(" -i, --indicated underlining is indicated via a separate line\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(USAGE_HELP, out);
- fputs(USAGE_VERSION, out);
+ PRINT_USAGE_HELP(30);
fprintf(out, USAGE_MAN_TAIL("ul(1)"));
--
2.12.3
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 3/6] misc: consolidate all --help option descriptions
2017-06-26 18:29 [PATCH 0/6] consolidate help/version option descriptions Ruediger Meier
2017-06-26 18:29 ` [PATCH 1/6] misc: revert to the old USAGE_HELP strings Ruediger Meier
2017-06-26 18:29 ` [PATCH 2/6] misc: introduce PRINT_USAGE_HELP() Ruediger Meier
@ 2017-06-26 18:29 ` Ruediger Meier
2017-06-26 18:29 ` [PATCH 4/6] blockdev: improve --help and man page Ruediger Meier
` (3 subsequent siblings)
6 siblings, 0 replies; 18+ messages in thread
From: Ruediger Meier @ 2017-06-26 18:29 UTC (permalink / raw)
To: util-linux
From: Ruediger Meier <ruediger.meier@ga-group.nl>
Now we are always using the same text also for commands
which had still hardcoded descriptions or where we can't
use the standard PRINT_USAGE_HELP macro.
Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
---
disk-utils/fsck.c | 4 ++--
disk-utils/fsck.cramfs.c | 4 ++--
disk-utils/mkfs.bfs.c | 5 ++---
disk-utils/mkfs.c | 5 +----
disk-utils/mkswap.c | 5 +++--
login-utils/chfn.c | 4 ++--
login-utils/chsh.c | 4 ++--
misc-utils/findmnt.c | 1 -
misc-utils/namei.c | 4 ++--
misc-utils/wipefs.c | 5 ++---
schedutils/taskset.c | 5 +++--
sys-utils/chcpu.c | 22 ++++++++++++----------
sys-utils/dmesg.c | 2 +-
sys-utils/prlimit.c | 4 ++--
term-utils/agetty.c | 4 ++--
term-utils/script.c | 4 ++--
term-utils/scriptreplay.c | 4 ++--
term-utils/setterm.c | 5 +++--
text-utils/col.c | 6 ++++--
text-utils/more.c | 4 ++--
20 files changed, 51 insertions(+), 50 deletions(-)
diff --git a/disk-utils/fsck.c b/disk-utils/fsck.c
index 918103ac0..c68d32ee5 100644
--- a/disk-utils/fsck.c
+++ b/disk-utils/fsck.c
@@ -1394,8 +1394,8 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -V explain what is being done\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(_(" -?, --help display this help and exit\n"), out);
- fputs(_(" --version output version information and exit\n"), out);
+ printf( " -?, --help %s\n", USAGE_HELP_TXT);
+ printf( " --version %s\n", USAGE_VERSION_TXT);
fputs(USAGE_SEPARATOR, out);
fputs(_("See the specific fsck.* commands for available fs-options."), out);
fprintf(out, USAGE_MAN_TAIL("fsck(8)"));
diff --git a/disk-utils/fsck.cramfs.c b/disk-utils/fsck.cramfs.c
index df13d2bb4..071cb0c61 100644
--- a/disk-utils/fsck.cramfs.c
+++ b/disk-utils/fsck.cramfs.c
@@ -120,9 +120,9 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -b, --blocksize <size> use this blocksize, defaults to page size\n"), out);
fputs(_(" --extract[=<dir>] test uncompression, optionally extract into <dir>\n"), out);
fputs(USAGE_SEPARATOR, out);
- PRINT_USAGE_HELP(16);
- fputs(USAGE_SEPARATOR, out);
+ PRINT_USAGE_HELP(26);
+ printf(USAGE_MAN_TAIL("fsck.cramfs(8)"));
exit(FSCK_EX_OK);
}
diff --git a/disk-utils/mkfs.bfs.c b/disk-utils/mkfs.bfs.c
index b19afa7cd..2cf1f313c 100644
--- a/disk-utils/mkfs.bfs.c
+++ b/disk-utils/mkfs.bfs.c
@@ -84,9 +84,8 @@ static void __attribute__((__noreturn__)) usage(void)
" -v, --verbose explain what is being done\n"
" -c this option is silently ignored\n"
" -l this option is silently ignored\n"
- " -V, --version output version information and exit\n"
- " -V as version must be only option\n"
- " -h, --help display this help and exit\n\n"));
+ ));
+ PRINT_USAGE_HELP(21);
fprintf(out, USAGE_MAN_TAIL("mkfs.bfs(8)"));
exit(EXIT_SUCCESS);
diff --git a/disk-utils/mkfs.c b/disk-utils/mkfs.c
index 25cc59d20..4a9de3e8d 100644
--- a/disk-utils/mkfs.c
+++ b/disk-utils/mkfs.c
@@ -55,12 +55,9 @@ static void __attribute__((__noreturn__)) usage(void)
fprintf(out, _(" <size> number of blocks to be used on the device\n"));
fprintf(out, _(" -V, --verbose explain what is being done;\n"
" specifying -V more than once will cause a dry-run\n"));
- fprintf(out, _(" -V, --version display version information and exit;\n"
- " -V as --version must be the only option\n"));
- fprintf(out, _(" -h, --help display this help text and exit\n"));
+ PRINT_USAGE_HELP(20);
fprintf(out, USAGE_MAN_TAIL("mkfs(8)"));
-
exit(EXIT_SUCCESS);
}
diff --git a/disk-utils/mkswap.c b/disk-utils/mkswap.c
index 73e5258ed..79097f220 100644
--- a/disk-utils/mkswap.c
+++ b/disk-utils/mkswap.c
@@ -160,9 +160,10 @@ static void __attribute__((__noreturn__)) usage(void)
" -L, --label LABEL specify label\n"
" -v, --swapversion NUM specify swap-space version number\n"
" -U, --uuid UUID specify the uuid to use\n"
- " -V, --version output version information and exit\n"
- " -h, --help display this help and exit\n\n"));
+ ));
+ PRINT_USAGE_HELP(27);
+ printf(USAGE_MAN_TAIL("mkswap(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/login-utils/chfn.c b/login-utils/chfn.c
index 7a57e9169..c86327099 100644
--- a/login-utils/chfn.c
+++ b/login-utils/chfn.c
@@ -104,8 +104,8 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -p, --office-phone <phone> office phone number\n"), fp);
fputs(_(" -h, --home-phone <phone> home phone number\n"), fp);
fputs(USAGE_SEPARATOR, fp);
- fputs(_(" -u, --help display this help and exit\n"), fp);
- fputs(_(" -v, --version output version information and exit\n"), fp);
+ printf( " -u, --help %s\n", USAGE_HELP_TXT);
+ printf( " -v, --version %s\n", USAGE_VERSION_TXT);
fprintf(fp, USAGE_MAN_TAIL("chfn(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/login-utils/chsh.c b/login-utils/chsh.c
index 1083583b9..895ce17c5 100644
--- a/login-utils/chsh.c
+++ b/login-utils/chsh.c
@@ -83,8 +83,8 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" -s, --shell <shell> specify login shell\n"), fp);
fputs(_(" -l, --list-shells print list of shells and exit\n"), fp);
fputs(USAGE_SEPARATOR, fp);
- fputs(_(" -u, --help display this help and exit\n"), fp);
- fputs(_(" -v, --version output version information and exit\n"), fp);
+ printf( " -u, --help %s\n", USAGE_HELP_TXT);
+ printf( " -v, --version %s\n", USAGE_VERSION_TXT);
fprintf(fp, USAGE_MAN_TAIL("chsh(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/misc-utils/findmnt.c b/misc-utils/findmnt.c
index b5e4d66d0..610314eb3 100644
--- a/misc-utils/findmnt.c
+++ b/misc-utils/findmnt.c
@@ -1243,7 +1243,6 @@ static void __attribute__((__noreturn__)) usage(void)
fputc('\n', out);
fputs(_(" -x, --verify verify mount table content (default is fstab)\n"), out);
fputs(_(" --verbose print more details\n"), out);
- fputc('\n', out);
fputs(USAGE_SEPARATOR, out);
PRINT_USAGE_HELP(24);
diff --git a/misc-utils/namei.c b/misc-utils/namei.c
index dcaf5d2eb..93989ec55 100644
--- a/misc-utils/namei.c
+++ b/misc-utils/namei.c
@@ -336,14 +336,14 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_("Follow a pathname until a terminal point is found.\n"), out);
fputs(USAGE_OPTIONS, out);
- fputs(_(" -h, --help displays this help text\n"
- " -V, --version output version information and exit\n"
+ fputs(_(
" -x, --mountpoints show mount point directories with a 'D'\n"
" -m, --modes show the mode bits of each file\n"
" -o, --owners show owner and group name of each file\n"
" -l, --long use a long listing format (-m -o -v) \n"
" -n, --nosymlinks don't follow symlinks\n"
" -v, --vertical vertical align of modes and owners\n"), out);
+ PRINT_USAGE_HELP(21);
fprintf(out, USAGE_MAN_TAIL("namei(1)"));
exit(EXIT_SUCCESS);
diff --git a/misc-utils/wipefs.c b/misc-utils/wipefs.c
index 0bd53253d..1eec9c404 100644
--- a/misc-utils/wipefs.c
+++ b/misc-utils/wipefs.c
@@ -465,16 +465,15 @@ usage(void)
fputs(_(" -a, --all wipe all magic strings (BE CAREFUL!)\n"
" -b, --backup create a signature backup in $HOME\n"
" -f, --force force erasure\n"
- " -h, --help show this help text\n"
" -n, --no-act do everything except the actual write() call\n"
" -o, --offset <num> offset to erase, in bytes\n"
" -p, --parsable print out in parsable instead of printable format\n"
" -q, --quiet suppress output messages\n"
" -t, --types <list> limit the set of filesystem, RAIDs or partition tables\n"
- " -V, --version output version information and exit\n"), out);
+ ), out);
+ PRINT_USAGE_HELP(21);
fprintf(out, USAGE_MAN_TAIL("wipefs(8)"));
-
exit(EXIT_SUCCESS);
}
diff --git a/schedutils/taskset.c b/schedutils/taskset.c
index c55b986fb..f5ac1586b 100644
--- a/schedutils/taskset.c
+++ b/schedutils/taskset.c
@@ -61,9 +61,10 @@ static void __attribute__((__noreturn__)) usage(void)
" -a, --all-tasks operate on all the tasks (threads) for a given pid\n"
" -p, --pid operate on existing given pid\n"
" -c, --cpu-list display and specify cpus in list format\n"
- " -h, --help display this help\n"
- " -V, --version output version information\n\n"));
+ ));
+ PRINT_USAGE_HELP(25);
+ fputs(USAGE_SEPARATOR, out);
fprintf(out, _(
"The default behavior is to run a new command:\n"
" %1$s 03 sshd -b 1024\n"
diff --git a/sys-utils/chcpu.c b/sys-utils/chcpu.c
index c0f568073..ff52b0c07 100644
--- a/sys-utils/chcpu.c
+++ b/sys-utils/chcpu.c
@@ -242,16 +242,18 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(USAGE_SEPARATOR, out);
fputs(_("Configure CPUs in a multi-processor system.\n"), out);
- puts(_( "\nOptions:\n"
- " -h, --help print this help\n"
- " -e, --enable <cpu-list> enable cpus\n"
- " -d, --disable <cpu-list> disable cpus\n"
- " -c, --configure <cpu-list> configure cpus\n"
- " -g, --deconfigure <cpu-list> deconfigure cpus\n"
- " -p, --dispatch <mode> set dispatching mode\n"
- " -r, --rescan trigger rescan of cpus\n"
- " -V, --version output version information and exit\n"));
-
+ fputs(USAGE_OPTIONS, stdout);
+ fputs(_(
+ " -e, --enable <cpu-list> enable cpus\n"
+ " -d, --disable <cpu-list> disable cpus\n"
+ " -c, --configure <cpu-list> configure cpus\n"
+ " -g, --deconfigure <cpu-list> deconfigure cpus\n"
+ " -p, --dispatch <mode> set dispatching mode\n"
+ " -r, --rescan trigger rescan of cpus\n"
+ ), stdout);
+ PRINT_USAGE_HELP(31);
+
+ printf(USAGE_MAN_TAIL("chcpu(8)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/dmesg.c b/sys-utils/dmesg.c
index eb47b9129..579635bbe 100644
--- a/sys-utils/dmesg.c
+++ b/sys-utils/dmesg.c
@@ -318,7 +318,7 @@ static void __attribute__((__noreturn__)) usage(void)
fprintf(out, " %7s - %s\n",
level_names[i].name,
_(level_names[i].help));
- fputs(USAGE_SEPARATOR, out);
+
fprintf(out, USAGE_MAN_TAIL("dmesg(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/sys-utils/prlimit.c b/sys-utils/prlimit.c
index 44db54ca5..eb3f12880 100644
--- a/sys-utils/prlimit.c
+++ b/sys-utils/prlimit.c
@@ -172,8 +172,8 @@ static void __attribute__((__noreturn__)) usage(void)
" --noheadings don't print headings\n"
" --raw use the raw output format\n"
" --verbose verbose output\n"
- " -h, --help display this help and exit\n"
- " -V, --version output version information and exit\n"), out);
+ ), out);
+ PRINT_USAGE_HELP(24);
fputs(_("\nResources Options:\n"), out);
fputs(_(" -c, --core maximum size of core files created\n"
diff --git a/term-utils/agetty.c b/term-utils/agetty.c
index 869513b22..ed74050c3 100644
--- a/term-utils/agetty.c
+++ b/term-utils/agetty.c
@@ -2110,8 +2110,8 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --delay <number> sleep seconds before prompt\n"), out);
fputs(_(" --nice <number> run login with this priority\n"), out);
fputs(_(" --reload reload prompts on running agetty instances\n"), out);
- fputs(_(" --help display this help and exit\n"), out);
- fputs(_(" --version output version information and exit\n"), out);
+ printf( " --help %s\n", USAGE_HELP_TXT);
+ printf( " --version %s\n", USAGE_VERSION_TXT);
fprintf(out, USAGE_MAN_TAIL("agetty(8)"));
exit(EXIT_SUCCESS);
diff --git a/term-utils/script.c b/term-utils/script.c
index a93a89ec9..9b0db0eb9 100644
--- a/term-utils/script.c
+++ b/term-utils/script.c
@@ -171,8 +171,8 @@ static void __attribute__((__noreturn__)) usage(void)
" --force use output file even when it is a link\n"
" -q, --quiet be quiet\n"
" -t, --timing[=<file>] output timing data to stderr (or to FILE)\n"
- " -V, --version output version information and exit\n"
- " -h, --help display this help and exit\n\n"), out);
+ ), out);
+ PRINT_USAGE_HELP(25);
fprintf(out, USAGE_MAN_TAIL("script(1)"));
exit(EXIT_SUCCESS);
diff --git a/term-utils/scriptreplay.c b/term-utils/scriptreplay.c
index a83f9a2eb..71598a0d1 100644
--- a/term-utils/scriptreplay.c
+++ b/term-utils/scriptreplay.c
@@ -52,8 +52,8 @@ usage(void)
" -s, --typescript <file> script terminal session output file\n"
" -d, --divisor <num> speed up or slow down execution with time divisor\n"
" -m, --maxdelay <num> wait at most this many seconds between updates\n"
- " -V, --version output version information and exit\n"
- " -h, --help display this help and exit\n\n"), out);
+ ), out);
+ PRINT_USAGE_HELP(25);
fprintf(out, USAGE_MAN_TAIL("scriptreplay(1)"));
exit(EXIT_SUCCESS);
diff --git a/term-utils/setterm.c b/term-utils/setterm.c
index 8ab5b45d7..60e0422e5 100644
--- a/term-utils/setterm.c
+++ b/term-utils/setterm.c
@@ -418,8 +418,9 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" --powerdown [0-60] set vesa powerdown interval in minutes\n"), out);
fputs(_(" --blength [0-2000] duration of the bell in milliseconds\n"), out);
fputs(_(" --bfreq <number> bell frequency in Hertz\n"), out);
- fputs(_(" --version show version information and exit\n"), out);
- fputs(_(" --help display this help and exit\n"), out);
+ printf( " --help %s\n", USAGE_HELP_TXT);
+ printf( " --version %s\n", USAGE_VERSION_TXT);
+
fprintf(out, USAGE_MAN_TAIL("setterm(1)"));
exit(EXIT_SUCCESS);
}
diff --git a/text-utils/col.c b/text-utils/col.c
index a473e55fb..c7ecc422f 100644
--- a/text-utils/col.c
+++ b/text-utils/col.c
@@ -142,9 +142,11 @@ static void __attribute__((__noreturn__)) usage(void)
" -h, --tabs convert spaces to tabs\n"
" -x, --spaces convert tabs to spaces\n"
" -l, --lines NUM buffer at least NUM lines\n"
- " -V, --version output version information and exit\n"
- " -H, --help display this help and exit\n\n"));
+ ));
+ printf( " -H, --help %s\n", USAGE_HELP_TXT);
+ printf( " -V, --version %s\n", USAGE_VERSION_TXT);
+ fputs(USAGE_SEPARATOR, out);
fprintf(out, _(
"%s reads from standard input and writes to standard output\n\n"),
program_invocation_short_name);
diff --git a/text-utils/more.c b/text-utils/more.c
index 35786567a..610711dbc 100644
--- a/text-utils/more.c
+++ b/text-utils/more.c
@@ -247,8 +247,8 @@ static void __attribute__((__noreturn__)) usage(void)
fputs(_(" +/<string> display file beginning from search string match\n"), out);
fputs(USAGE_SEPARATOR, out);
- fputs(_(" --help display this help and exit\n"), out);
- fputs(_(" -V, --version output version information and exit\n"), out);
+ printf( " --help %s\n", USAGE_HELP_TXT);
+ printf( " -V, --version %s\n", USAGE_VERSION_TXT);
fprintf(out, USAGE_MAN_TAIL("more(1)"));
exit(EXIT_SUCCESS);
}
--
2.12.3
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 4/6] blockdev: improve --help and man page
2017-06-26 18:29 [PATCH 0/6] consolidate help/version option descriptions Ruediger Meier
` (2 preceding siblings ...)
2017-06-26 18:29 ` [PATCH 3/6] misc: consolidate all --help option descriptions Ruediger Meier
@ 2017-06-26 18:29 ` Ruediger Meier
2017-06-26 18:29 ` [PATCH 5/6] login: add --help text Ruediger Meier
` (2 subsequent siblings)
6 siblings, 0 replies; 18+ messages in thread
From: Ruediger Meier @ 2017-06-26 18:29 UTC (permalink / raw)
To: util-linux
From: Ruediger Meier <ruediger.meier@ga-group.nl>
Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
---
disk-utils/blockdev.8 | 9 +++++++--
disk-utils/blockdev.c | 34 +++++++++++++++++++++++-----------
2 files changed, 30 insertions(+), 13 deletions(-)
diff --git a/disk-utils/blockdev.8 b/disk-utils/blockdev.8
index c9eeb9b41..0f3291391 100644
--- a/disk-utils/blockdev.8
+++ b/disk-utils/blockdev.8
@@ -17,13 +17,14 @@ blockdev \- call block device ioctls from the command line
.B blockdev
.B \-\-report
.RI [ device \&...\&]
+.br
+.B blockdev
+.RB \-h | \-V
.SH DESCRIPTION
The utility
.B blockdev
allows one to call block device ioctls from the command line.
.SH OPTIONS
-.IP "\fB\-V\fP"
-Print version and exit.
.IP "\fB\-q\fP"
Be quiet.
.IP "\fB\-v\fP"
@@ -32,6 +33,10 @@ Be verbose.
Print a report for the specified device. It is possible to give multiple
devices. If none is given, all devices which appear in /proc/partitions are
shown. Note that the partition StartSec is in 512-byte sectors.
+.IP "\fB\-h\fR, \fB\-\-help\fR"
+Display help text and exit.
+.IP "\fB\-V\fR, \fB\-\-version\fR"
+Print version and exit.
.SH COMMANDS
It is possible to give multiple devices and multiple commands.
.IP "\fB\-\-flushbufs\fP"
diff --git a/disk-utils/blockdev.c b/disk-utils/blockdev.c
index 4760e021b..ef502e0a3 100644
--- a/disk-utils/blockdev.c
+++ b/disk-utils/blockdev.c
@@ -180,27 +180,39 @@ static const struct bdc bdcms[] =
static void __attribute__((__noreturn__)) usage(void)
{
- FILE * out = stdout;
size_t i;
- fprintf(out, _("\nUsage:\n"
- " %1$s -V\n"
- " %1$s --report [devices]\n"
- " %1$s [-v|-q] commands devices\n\n"
- "Available commands:\n"), program_invocation_short_name);
-
- fprintf(out, _(" %-25s get size in 512-byte sectors\n"), "--getsz");
+ fputs(USAGE_HEADER, stdout);
+ printf(_(
+ " %1$s [-v|-q] commands devices\n"
+ " %1$s --report [devices]\n"
+ " %1$s -h|-V\n"
+ ), program_invocation_short_name);
+
+ fputs(USAGE_SEPARATOR, stdout);
+ puts( _("Call block device ioctls from the command line."));
+
+ fputs(USAGE_OPTIONS, stdout);
+ puts( _(" -q quiet mode"));
+ puts( _(" -v verbose mode"));
+ puts( _(" --report print report for specified (or all) devices"));
+ fputs(USAGE_SEPARATOR, stdout);
+ PRINT_USAGE_HELP(16);
+
+ fputs(USAGE_SEPARATOR, stdout);
+ puts( _("Available commands:"));
+ printf(_(" %-25s get size in 512-byte sectors\n"), "--getsz");
for (i = 0; i < ARRAY_SIZE(bdcms); i++) {
if (bdcms[i].argname)
- fprintf(out, " %s %-*s %s\n", bdcms[i].name,
+ printf(" %s %-*s %s\n", bdcms[i].name,
(int)(24 - strlen(bdcms[i].name)),
bdcms[i].argname, _(bdcms[i].help));
else
- fprintf(out, " %-25s %s\n", bdcms[i].name,
+ printf(" %-25s %s\n", bdcms[i].name,
_(bdcms[i].help));
}
- fprintf(out, USAGE_MAN_TAIL("blockdev(1)"));
+ printf(USAGE_MAN_TAIL("blockdev(1)"));
exit(EXIT_SUCCESS);
}
--
2.12.3
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 5/6] login: add --help text
2017-06-26 18:29 [PATCH 0/6] consolidate help/version option descriptions Ruediger Meier
` (3 preceding siblings ...)
2017-06-26 18:29 ` [PATCH 4/6] blockdev: improve --help and man page Ruediger Meier
@ 2017-06-26 18:29 ` Ruediger Meier
2017-06-26 18:29 ` [PATCH 6/6] misc: update --help content again Ruediger Meier
2017-06-27 9:49 ` [PATCH 0/6] consolidate help/version option descriptions Karel Zak
6 siblings, 0 replies; 18+ messages in thread
From: Ruediger Meier @ 2017-06-26 18:29 UTC (permalink / raw)
To: util-linux
From: Ruediger Meier <ruediger.meier@ga-group.nl>
Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
---
login-utils/login.c | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/login-utils/login.c b/login-utils/login.c
index ee06d03e8..08b2d3564 100644
--- a/login-utils/login.c
+++ b/login-utils/login.c
@@ -1101,6 +1101,14 @@ static void __attribute__((__noreturn__)) usage(void)
printf(_(" %s [-p] [-h <host>] [-H] [[-f] <username>]\n"), program_invocation_short_name);
fputs(USAGE_SEPARATOR, stdout);
fputs(_("Begin a session on the system.\n"), stdout);
+
+ fputs(USAGE_OPTIONS, stdout);
+ puts(_(" -p do not destroy the environment"));
+ puts(_(" -f skip a second login authentication"));
+ puts(_(" -h <host> hostname to be used for utmp logging"));
+ puts(_(" -H suppress hostname in the login prompt"));
+ printf(" --help %s\n", USAGE_HELP_TXT);
+ printf(" -V, --version %s\n", USAGE_VERSION_TXT);
printf(USAGE_MAN_TAIL("login(1)"));
exit(EXIT_SUCCESS);
}
--
2.12.3
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 6/6] misc: update --help content again
2017-06-26 18:29 [PATCH 0/6] consolidate help/version option descriptions Ruediger Meier
` (4 preceding siblings ...)
2017-06-26 18:29 ` [PATCH 5/6] login: add --help text Ruediger Meier
@ 2017-06-26 18:29 ` Ruediger Meier
2017-06-27 12:42 ` J William Piggott
2017-06-27 9:49 ` [PATCH 0/6] consolidate help/version option descriptions Karel Zak
6 siblings, 1 reply; 18+ messages in thread
From: Ruediger Meier @ 2017-06-26 18:29 UTC (permalink / raw)
To: util-linux; +Cc: J William Piggott
From: Ruediger Meier <ruediger.meier@ga-group.nl>
We change
-h, --help display this help and exit
-V, --version output version information and exit
to
-h, --help display this help
-V, --version print version
Some thoughts about this:
* use "display" for --help because it matches better if we
would add pager support (like git --help)
* "print" for --version to be different
* "this" for --help is important to make clear that running
--help would not give you any better information than the
one you see already
* remove "information and exit" because it's bloat for the
short-help, everybody knows what it does if it exists
In the manpages we should use the old, longer but more correct
descriptions, inclusive a reminder if --help/--version are only
working when used as the only option. Note the term "version
information" indicates that we don't only print a single version
number.
CC: J William Piggott <elseifthen@gmx.com>
Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
---
include/c.h | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/include/c.h b/include/c.h
index ce5551535..be7e6fd53 100644
--- a/include/c.h
+++ b/include/c.h
@@ -316,8 +316,8 @@ static inline int xusleep(useconds_t usec)
#define USAGE_COLUMNS _("\nAvailable output columns:\n")
#define USAGE_SEPARATOR "\n"
-#define USAGE_HELP_TXT _("display this help and exit")
-#define USAGE_VERSION_TXT _("output version information and exit")
+#define USAGE_HELP_TXT _("display this help")
+#define USAGE_VERSION_TXT _("print version")
#define PRINT_USAGE_HELP(marg_dsc) \
printf( \
--
2.12.3
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 2/6] misc: introduce PRINT_USAGE_HELP()
2017-06-26 18:29 ` [PATCH 2/6] misc: introduce PRINT_USAGE_HELP() Ruediger Meier
@ 2017-06-27 9:46 ` Karel Zak
2017-06-27 10:48 ` Rüdiger Meier
0 siblings, 1 reply; 18+ messages in thread
From: Karel Zak @ 2017-06-27 9:46 UTC (permalink / raw)
To: Ruediger Meier; +Cc: util-linux
On Mon, Jun 26, 2017 at 08:29:48PM +0200, Ruediger Meier wrote:
> --- a/include/c.h
> +++ b/include/c.h
> @@ -315,8 +315,18 @@ static inline int xusleep(useconds_t usec)
> #define USAGE_COMMANDS _("\nCommands:\n")
> #define USAGE_COLUMNS _("\nAvailable output columns:\n")
> #define USAGE_SEPARATOR "\n"
> -#define USAGE_HELP _(" -h, --help display this help and exit\n")
> -#define USAGE_VERSION _(" -V, --version output version information and exit\n")
> +
> +#define USAGE_HELP_TXT _("display this help and exit")
> +#define USAGE_VERSION_TXT _("output version information and exit")
> +
> +#define PRINT_USAGE_HELP(marg_dsc) \
> + printf( \
> + "%-" #marg_dsc "s%s\n" \
> + "%-" #marg_dsc "s%s\n" \
> + , " -h, --help", USAGE_HELP_TXT \
> + , " -V, --version", USAGE_VERSION_TXT \
> + )
Would be possible to use lowercase for the macro name?
For example USAGE_HELP_TXT is fine, but for something like function I
would prefer
#define print_usage_help(marg_dsc)
and what about USAGE_SEPARATOR that we have always before --help?
Maybe we can add \n to the print_usage_help() too.
> --- a/login-utils/last.c
> +++ b/login-utils/last.c
> @@ -589,8 +589,7 @@ static void __attribute__((__noreturn__)) usage(const struct last_control *ctl)
> " notime|short|full|iso\n"), out);
>
> fputs(USAGE_SEPARATOR, out);
> - fputs(USAGE_HELP, out);
> - fputs(USAGE_VERSION, out);
> + PRINT_USAGE_HELP(22);
> fprintf(out, USAGE_MAN_TAIL("last(1)"));
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 0/6] consolidate help/version option descriptions
2017-06-26 18:29 [PATCH 0/6] consolidate help/version option descriptions Ruediger Meier
` (5 preceding siblings ...)
2017-06-26 18:29 ` [PATCH 6/6] misc: update --help content again Ruediger Meier
@ 2017-06-27 9:49 ` Karel Zak
6 siblings, 0 replies; 18+ messages in thread
From: Karel Zak @ 2017-06-27 9:49 UTC (permalink / raw)
To: Ruediger Meier; +Cc: util-linux
On Mon, Jun 26, 2017 at 08:29:46PM +0200, Ruediger Meier wrote:
> From: Ruediger Meier <ruediger.meier@ga-group.nl>
>
> Hope you will like it.
>
> The final description strings (last patch) are just a
> proposal. ALso maybe better macro names!?
USAGE_HELP_TXT rename to USAGE_OPTSTR_HELP ?
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/6] misc: introduce PRINT_USAGE_HELP()
2017-06-27 9:46 ` Karel Zak
@ 2017-06-27 10:48 ` Rüdiger Meier
2017-06-27 12:19 ` Karel Zak
0 siblings, 1 reply; 18+ messages in thread
From: Rüdiger Meier @ 2017-06-27 10:48 UTC (permalink / raw)
To: Karel Zak; +Cc: util-linux
On 06/27/2017 11:46 AM, Karel Zak wrote:
> On Mon, Jun 26, 2017 at 08:29:48PM +0200, Ruediger Meier wrote:
>> --- a/include/c.h
>> +++ b/include/c.h
>> @@ -315,8 +315,18 @@ static inline int xusleep(useconds_t usec)
>> #define USAGE_COMMANDS _("\nCommands:\n")
>> #define USAGE_COLUMNS _("\nAvailable output columns:\n")
>> #define USAGE_SEPARATOR "\n"
>> -#define USAGE_HELP _(" -h, --help display this help and exit\n")
>> -#define USAGE_VERSION _(" -V, --version output version information and exit\n")
>> +
>> +#define USAGE_HELP_TXT _("display this help and exit")
>> +#define USAGE_VERSION_TXT _("output version information and exit")
>> +
>> +#define PRINT_USAGE_HELP(marg_dsc) \
>> + printf( \
>> + "%-" #marg_dsc "s%s\n" \
>> + "%-" #marg_dsc "s%s\n" \
>> + , " -h, --help", USAGE_HELP_TXT \
>> + , " -V, --version", USAGE_VERSION_TXT \
>> + )
>
> Would be possible to use lowercase for the macro name?
>
> For example USAGE_HELP_TXT is fine, but for something like function I
> would prefer
>
> #define print_usage_help(marg_dsc)
I've updated on github to
#define USAGE_OPTSTR_HELP _("display this help")
#define USAGE_OPTSTR_VERSION _("print version")
#define print_usage_help_options(marg_dsc) \
[...]
> and what about USAGE_SEPARATOR that we have always before --help?
> Maybe we can add \n to the print_usage_help() too.
No, because
1. There are commands with help options only:
$ ctrlaltdel --help
[...]
Options:
-h, --help display this help
-V, --version print version
2. Since we have we help descriptions now aligned we do not need
the separator always IMO. ipcs(1) and also others which
still don't have separators are looking ok:
$ ipcs --help
Usage:
ipcs [resource-option...] [output-option]
ipcs -m|-q|-s -i <id>
Show information on IPC facilities.
Options:
-i, --id <id> print details on resource identified by <id>
-h, --help display this help
-V, --version print version
Resource options:
-m, --shmems shared memory segments
[...]
cu,
Rudi
>> --- a/login-utils/last.c
>> +++ b/login-utils/last.c
>> @@ -589,8 +589,7 @@ static void __attribute__((__noreturn__)) usage(const struct last_control *ctl)
>> " notime|short|full|iso\n"), out);
>>
>> fputs(USAGE_SEPARATOR, out);
>> - fputs(USAGE_HELP, out);
>> - fputs(USAGE_VERSION, out);
>> + PRINT_USAGE_HELP(22);
>> fprintf(out, USAGE_MAN_TAIL("last(1)"));
>
>
> Karel
>
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/6] misc: introduce PRINT_USAGE_HELP()
2017-06-27 10:48 ` Rüdiger Meier
@ 2017-06-27 12:19 ` Karel Zak
0 siblings, 0 replies; 18+ messages in thread
From: Karel Zak @ 2017-06-27 12:19 UTC (permalink / raw)
To: Rüdiger Meier; +Cc: util-linux
On Tue, Jun 27, 2017 at 12:48:44PM +0200, Rüdiger Meier wrote:
>
>
> On 06/27/2017 11:46 AM, Karel Zak wrote:
> > On Mon, Jun 26, 2017 at 08:29:48PM +0200, Ruediger Meier wrote:
> > > --- a/include/c.h
> > > +++ b/include/c.h
> > > @@ -315,8 +315,18 @@ static inline int xusleep(useconds_t usec)
> > > #define USAGE_COMMANDS _("\nCommands:\n")
> > > #define USAGE_COLUMNS _("\nAvailable output columns:\n")
> > > #define USAGE_SEPARATOR "\n"
> > > -#define USAGE_HELP _(" -h, --help display this help and exit\n")
> > > -#define USAGE_VERSION _(" -V, --version output version information and exit\n")
> > > +
> > > +#define USAGE_HELP_TXT _("display this help and exit")
> > > +#define USAGE_VERSION_TXT _("output version information and exit")
> > > +
> > > +#define PRINT_USAGE_HELP(marg_dsc) \
> > > + printf( \
> > > + "%-" #marg_dsc "s%s\n" \
> > > + "%-" #marg_dsc "s%s\n" \
> > > + , " -h, --help", USAGE_HELP_TXT \
> > > + , " -V, --version", USAGE_VERSION_TXT \
> > > + )
> >
> > Would be possible to use lowercase for the macro name?
> >
> > For example USAGE_HELP_TXT is fine, but for something like function I
> > would prefer
> >
> > #define print_usage_help(marg_dsc)
>
> I've updated on github to
Cool, merged.
> > and what about USAGE_SEPARATOR that we have always before --help?
> > Maybe we can add \n to the print_usage_help() too.
>
> No, because
>
> 1. There are commands with help options only:
>
> $ ctrlaltdel --help
> [...]
> Options:
> -h, --help display this help
> -V, --version print version
>
> 2. Since we have we help descriptions now aligned we do not need
> the separator always IMO. ipcs(1) and also others which
> still don't have separators are looking ok:
I see (I've expected this reply :-).
Thanks!
Karel
--
Karel Zak <kzak@redhat.com>
http://karelzak.blogspot.com
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 6/6] misc: update --help content again
2017-06-26 18:29 ` [PATCH 6/6] misc: update --help content again Ruediger Meier
@ 2017-06-27 12:42 ` J William Piggott
2017-06-27 13:26 ` Rüdiger Meier
0 siblings, 1 reply; 18+ messages in thread
From: J William Piggott @ 2017-06-27 12:42 UTC (permalink / raw)
To: Ruediger Meier, util-linux
On 06/26/2017 02:29 PM, Ruediger Meier wrote:
> From: Ruediger Meier <ruediger.meier@ga-group.nl>
>
> We change
>
> -h, --help display this help and exit
> -V, --version output version information and exit
>
> to
>
> -h, --help display this help
> -V, --version print version
>
> Some thoughts about this:
>
> * use "display" for --help because it matches better if we
> would add pager support (like git --help)
> * "print" for --version to be different
To be different why? It makes it sound like help and version will not
have the same action. Laymen think 'print' means send to the printer.
Translators will have to figure out which different words to use.
What is broken by:
-h, --help display this help
-V, --version display version
I really think it is a good idea to use consistent language for
comparable actions. It is easier to comprehend, especially for
non-native speakers. Once they understand the meaning of a term,
possibly from a context that they the understand well, then that
knowledge is transferable to other contexts. Why add confusion by
constantly interchanging term synonyms?
> * "this" for --help is important to make clear that running
> --help would not give you any better information than the
> one you see already
> * remove "information and exit" because it's bloat for the
> short-help, everybody knows what it does if it exists
>
> In the manpages we should use the old, longer but more correct
> descriptions, inclusive a reminder if --help/--version are only
> working when used as the only option. Note the term "version
> information" indicates that we don't only print a single version
> number.
>
> CC: J William Piggott <elseifthen@gmx.com>
> Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
> ---
> include/c.h | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/include/c.h b/include/c.h
> index ce5551535..be7e6fd53 100644
> --- a/include/c.h
> +++ b/include/c.h
> @@ -316,8 +316,8 @@ static inline int xusleep(useconds_t usec)
> #define USAGE_COLUMNS _("\nAvailable output columns:\n")
> #define USAGE_SEPARATOR "\n"
>
> -#define USAGE_HELP_TXT _("display this help and exit")
> -#define USAGE_VERSION_TXT _("output version information and exit")
> +#define USAGE_HELP_TXT _("display this help")
> +#define USAGE_VERSION_TXT _("print version")
>
> #define PRINT_USAGE_HELP(marg_dsc) \
> printf( \
>
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 6/6] misc: update --help content again
2017-06-27 12:42 ` J William Piggott
@ 2017-06-27 13:26 ` Rüdiger Meier
2017-06-27 15:12 ` J William Piggott
0 siblings, 1 reply; 18+ messages in thread
From: Rüdiger Meier @ 2017-06-27 13:26 UTC (permalink / raw)
To: J William Piggott, util-linux
On 06/27/2017 02:42 PM, J William Piggott wrote:
>
>
> On 06/26/2017 02:29 PM, Ruediger Meier wrote:
>> From: Ruediger Meier <ruediger.meier@ga-group.nl>
>>
>> We change
>>
>> -h, --help display this help and exit
>> -V, --version output version information and exit
>>
>> to
>>
>> -h, --help display this help
>> -V, --version print version
>>
>> Some thoughts about this:
>>
>> * use "display" for --help because it matches better if we
>> would add pager support (like git --help)
>> * "print" for --version to be different
>
> To be different why?
Because AFAIR somewhere Karel or somebody else mentioned that we
could add auto-pager support on terminal for long --help output
(like findmnt) or otherwise colored help texts. This would be a
difference, doing more than printf only.
--version just print and exit
--help display something and keep the display (pager) open.
It makes it sound like help and version will not
> have the same action. Laymen think 'print' means send to the printer.
> Translators will have to figure out which different words to use.
Hehe, I have never thought about printers. But for my bad English
"display" sounds more like TV show or graphical X-display. ;)
Seriously IMO "print" is the right term for command-line and shell
environment . It's also more often used than "display" in POSIX and
coreutils manpages.
> What is broken by:
>
> -h, --help display this help
> -V, --version display version
>
> I really think it is a good idea to use consistent language for
Consistent language is not always human-friendly and can also be
more hard or boring to read. See
$ man bash | tr ' ' '\n'| grep display | wc -l
67
$ man bash | tr ' ' '\n'| grep print | wc -l
70
Try to imagine this manpage if they would always use the same word.
> comparable actions. It is easier to comprehend, especially for
> non-native speakers. Once they understand the meaning of a term,
> possibly from a context that they the understand well, then that
> knowledge is transferable to other contexts. Why add confusion by
> constantly interchanging term synonyms?
Anyways, I'm also fine with display. This was just my favorite
proposal.
cu,
Rudi
>
>> * "this" for --help is important to make clear that running
>> --help would not give you any better information than the
>> one you see already
>> * remove "information and exit" because it's bloat for the
>> short-help, everybody knows what it does if it exists
>>
>> In the manpages we should use the old, longer but more correct
>> descriptions, inclusive a reminder if --help/--version are only
>> working when used as the only option. Note the term "version
>> information" indicates that we don't only print a single version
>> number.
>>
>> CC: J William Piggott <elseifthen@gmx.com>
>> Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
>> ---
>> include/c.h | 4 ++--
>> 1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/include/c.h b/include/c.h
>> index ce5551535..be7e6fd53 100644
>> --- a/include/c.h
>> +++ b/include/c.h
>> @@ -316,8 +316,8 @@ static inline int xusleep(useconds_t usec)
>> #define USAGE_COLUMNS _("\nAvailable output columns:\n")
>> #define USAGE_SEPARATOR "\n"
>>
>> -#define USAGE_HELP_TXT _("display this help and exit")
>> -#define USAGE_VERSION_TXT _("output version information and exit")
>> +#define USAGE_HELP_TXT _("display this help")
>> +#define USAGE_VERSION_TXT _("print version")
>>
>> #define PRINT_USAGE_HELP(marg_dsc) \
>> printf( \
>>
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 6/6] misc: update --help content again
2017-06-27 13:26 ` Rüdiger Meier
@ 2017-06-27 15:12 ` J William Piggott
2017-06-27 16:35 ` Rüdiger Meier
0 siblings, 1 reply; 18+ messages in thread
From: J William Piggott @ 2017-06-27 15:12 UTC (permalink / raw)
To: Rüdiger Meier, util-linux
On 06/27/2017 09:26 AM, Rüdiger Meier wrote:
>
>
> On 06/27/2017 02:42 PM, J William Piggott wrote:
>>
>>
>> On 06/26/2017 02:29 PM, Ruediger Meier wrote:
>>> From: Ruediger Meier <ruediger.meier@ga-group.nl>
>>>
>>>
>>> We change
>>>
>>> -h, --help display this help and exit -V, --version output
>>> version information and exit
>>>
>>> to
>>>
>>> -h, --help display this help -V, --version print version
>>>
>>>
>>> Some thoughts about this:
>>>
>>> * use "display" for --help because it matches better if we
>>>
>>> would add pager support (like git --help)
>>>
>>> * "print" for --version to be different
>>>
>>
>> To be different why?
>>
>
> Because AFAIR somewhere Karel or somebody else mentioned that we could
> add auto-pager support on terminal for long --help output (like
> findmnt) or otherwise colored help texts. This would be a difference,
> doing more than printf only.
>
If I understand you correctly, using the word 'display' should imply
that a pager might be used?
When reading open source documentation, messages, etc., I make
absolutely no distinction between: show, to stdout, display, print, or
output; to me they are absolute synonyms unless there is additional
language stating otherwise; such as:
>
> --version just print and exit
>
> --help display something and keep the display (pager) open.
>
With this additional language it makes no difference for us whether we
use the same term, print or display, in both statements. But to a new
student of open source using different terms changes the meaning; or at
the very least is ambiguous. They may wonder: there must be a reason
they are using these different terms; what is it?
>> It makes it sound like help and version will not
>> have the same action. Laymen think 'print' means send to the
>> printer.
>>
>> Translators will have to figure out which different words to use.
>
> Hehe, I have never thought about printers. But for my bad English
> "display" sounds more like TV show or graphical X-display. ;)
>
> Seriously IMO "print" is the right term for command-line and shell
> environment . It's also more often used than "display" in POSIX and
> coreutils manpages.
>
Using the term 'print' is residue from the days when a printer was the
only human readable output. I think it is unfortunate that it has now
become synonymous with sending output to the terminal display monitor.
However, whatever the consensus is for the best term, all I'm hoping for
is to use it consistently instead of all the other synonyms.
>> What is broken by:
>>
>> -h, --help display this help
>> -V, --version display version
>>
>> I really think it is a good idea to use consistent language for
>
> Consistent language is not always human-friendly
For comprehension of technical material, consistency is not only more
human-friendly, it is imperative.
> and can also be more hard or boring to read. See
We are not talking about a novel. Technical material by necessity is
boring to read (unless you are enthusiastic about learning). Think
textbooks.
>
> $ man bash | tr ' ' '\n'| grep display | wc -l 67 $ man bash | tr ' '
> '\n'| grep print | wc -l 70
>
> Try to imagine this manpage if they would always use the same word.
>From a comprehension standpoint, I imagine it would be an improvement.
I have more that once been confused by bash(1) using ambiguous terms.
>
>> comparable actions. It is easier to comprehend, especially for
>> non-native speakers. Once they understand the meaning of a term,
>> possibly from a context that they the understand well, then that
>> knowledge is transferable to other contexts. Why add confusion by
>> constantly interchanging term synonyms?
>
> Anyways, I'm also fine with display. This was just my favorite
> proposal.
I know when it comes to docs and strings that there is a long tradition
for hackers interjecting humor, wisecracks and generally not taking
things to seriously. I'm generally of that mindset myself. However, it
wasn't so long ago when I began using Linux that I cannot remember being
confused by all of the interchanging of synonyms. Promoting this idea of
using consistent language doesn't matter that much to me personally, I'm
trying to help new students.
I also have the impression that many of us are working to make open
source polished and professional. I believe that technical writing
should be focused on comprehension and that using consistent language,
especially for terms, is imperative to that end.
>
> cu, Rudi
>
>>
>>> * "this" for --help is important to make clear that running
>>>
>>>
>>> --help would not give you any better information than the
>>>
>>> one you see already
>>>
>>> * remove "information and exit" because it's bloat for the
>>>
>>>
>>> short-help, everybody knows what it does if it exists
>>>
>>> In the manpages we should use the old, longer but more correct
>>>
>>> descriptions, inclusive a reminder if --help/--version are only
>>> working when used as the only option. Note the term "version
>>> information" indicates that we don't only print a single version
>>>
>>> number.
>>>
>>>
>>> CC: J William Piggott <elseifthen@gmx.com>
>>>
>>> Signed-off-by: Ruediger Meier <ruediger.meier@ga-group.nl>
>>>
>>> ---
>>>
>>> include/c.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
>>>
>>>
>>> diff --git a/include/c.h b/include/c.h
>>>
>>> index ce5551535..be7e6fd53 100644 --- a/include/c.h
>>>
>>> +++ b/include/c.h
>>>
>>> @@ -316,8 +316,8 @@ static inline int xusleep(useconds_t usec)
>>>
>>> #define USAGE_COLUMNS _("\nAvailable output columns:\n")
>>>
>>>
>>> #define USAGE_SEPARATOR "\n"
>>>
>>> -#define USAGE_HELP_TXT _("display this help and exit") -#define
>>> USAGE_VERSION_TXT _("output version information and exit") +#define
>>> USAGE_HELP_TXT _("display this help") +#define USAGE_VERSION_TXT
>>> _("print version")
>>>
>>>
>>> #define PRINT_USAGE_HELP(marg_dsc) \
>>>
>>> printf( \
>>>
> -- To unsubscribe from this list: send the line "unsubscribe
> util-linux" in
>
> the body of a message to majordomo@vger.kernel.org
>
> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
>
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 6/6] misc: update --help content again
2017-06-27 15:12 ` J William Piggott
@ 2017-06-27 16:35 ` Rüdiger Meier
2017-06-27 19:08 ` J William Piggott
0 siblings, 1 reply; 18+ messages in thread
From: Rüdiger Meier @ 2017-06-27 16:35 UTC (permalink / raw)
To: J William Piggott, util-linux
On 06/27/2017 05:12 PM, J William Piggott wrote:
>
>
> On 06/27/2017 09:26 AM, Rüdiger Meier wrote:
>>
>>
>> On 06/27/2017 02:42 PM, J William Piggott wrote:
>>>
>>>
>>> On 06/26/2017 02:29 PM, Ruediger Meier wrote:
>>>> From: Ruediger Meier <ruediger.meier@ga-group.nl>
>>>>
>>>>
>>>> We change
>>>>
>>>> -h, --help display this help and exit -V, --version output
>>>> version information and exit
>>>>
>>>> to
>>>>
>>>> -h, --help display this help -V, --version print version
>>>>
>>>>
>>>> Some thoughts about this:
>>>>
>>>> * use "display" for --help because it matches better if we
>>>>
>>>> would add pager support (like git --help)
>>>>
>>>> * "print" for --version to be different
>>>>
>>>
>>> To be different why?
>>>
>>
>> Because AFAIR somewhere Karel or somebody else mentioned that we could
>> add auto-pager support on terminal for long --help output (like
>> findmnt) or otherwise colored help texts. This would be a difference,
>> doing more than printf only.
>>
>
> If I understand you correctly, using the word 'display' should imply
> that a pager might be used?
>
> When reading open source documentation, messages, etc., I make
> absolutely no distinction between: show, to stdout, display, print, or
> output; to me they are absolute synonyms unless there is additional
> language stating otherwise; such as:
Maybe I make this difference between display and print because there
is a *print*() function in almost any programming language I know. But
*display*() or *show*() are usually only known in any graphical
libraries (widget toolkits, plotting, etc.).
BTW regarding show, see
--status don't output anything, status code shows success
So something can be "shown" without any output at all ;)
>>
>> --version just print and exit
>>
>> --help display something and keep the display (pager) open.
>>
>
> With this additional language it makes no difference for us whether we
> use the same term, print or display, in both statements. But to a new
> student of open source using different terms changes the meaning; or at
> the very least is ambiguous. They may wonder: there must be a reason
> they are using these different terms; what is it?
>
>>> It makes it sound like help and version will not
>>> have the same action. Laymen think 'print' means send to the
>>> printer.
>>>
>>> Translators will have to figure out which different words to use.
>>
>> Hehe, I have never thought about printers. But for my bad English
>> "display" sounds more like TV show or graphical X-display. ;)
>>
>> Seriously IMO "print" is the right term for command-line and shell
>> environment . It's also more often used than "display" in POSIX and
>> coreutils manpages.
>>
>
> Using the term 'print' is residue from the days when a printer was the
> only human readable output. I think it is unfortunate that it has now
> become synonymous with sending output to the terminal display monitor.
>
> However, whatever the consensus is for the best term, all I'm hoping for
> is to use it consistently instead of all the other synonyms.
>
>>> What is broken by:
>>>
>>> -h, --help display this help
>>> -V, --version display version
>>>
>>> I really think it is a good idea to use consistent language for
>>
>> Consistent language is not always human-friendly
>
> For comprehension of technical material, consistency is not only more
> human-friendly, it is imperative.
>
>> and can also be more hard or boring to read. See
>
> We are not talking about a novel. Technical material by necessity is
> boring to read (unless you are enthusiastic about learning). Think
> textbooks.
Yes, but I find my eyes are more relaxed when not everything looks
like the same pattern with minor differences. Worst case example:
--show-file-size display the size of the file
--show-link-size display the size of the link
--show-file-color display the color of the file
--show-link-color display the color of the link
--show-file-taste display the taste of the file
--show-link-taste display the taste of the link
This makes me ill. So I don't like to read the term "display" or
"print" 20 times on the same screen. The --help and --version
options are boring enough already. I see no problem mixing
print and display there.
A bit reordering and rewording makes it better:
--show-file-size display the size of the file
--show-file-color display the color of the file
--show-file-taste display the taste of the file
--show-link-size print link size
--show-link-color print link color
--show-link-taste print link taste
>>> comparable actions. It is easier to comprehend, especially for
>>> non-native speakers. Once they understand the meaning of a term,
>>> possibly from a context that they the understand well, then that
>>> knowledge is transferable to other contexts. Why add confusion by
>>> constantly interchanging term synonyms?
>>
>> Anyways, I'm also fine with display. This was just my favorite
>> proposal.
>
> I know when it comes to docs and strings that there is a long tradition
> for hackers interjecting humor, wisecracks and generally not taking
> things to seriously. I'm generally of that mindset myself. However, it
> wasn't so long ago when I began using Linux that I cannot remember being
> confused by all of the interchanging of synonyms. Promoting this idea of
> using consistent language doesn't matter that much to me personally, I'm
> trying to help new students.
FYI I just investigated the coreutils history. They changed their strings
the last time in 1993. Maybe that's also kind of consistent in tradition.
This was their change 24 years ago
- --help provide this help\n\
- --version show program version\n");
+ --help display this help and exit\n\
+ --version output version information and exit\n");
Grepping all their manpages shows that they are using "display" almost only
in this single help string, normally using "print" and sometimes "show".
In their real (info) documentation they use:
`--help'
Print a usage message listing all available options, then exit
successfully.
`--version'
Print the version number, then exit successfully.
I think these ones would fit also for our manpages. I like their statement
"listing *all* available options". It was not always clear to me whether
or not I should hide unimportant/redundant options from --help output.
cu,
Rudi
> I also have the impression that many of us are working to make open
> source polished and professional. I believe that technical writing
> should be focused on comprehension and that using consistent language,
> especially for terms, is imperative to that end.
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 6/6] misc: update --help content again
2017-06-27 16:35 ` Rüdiger Meier
@ 2017-06-27 19:08 ` J William Piggott
2017-06-28 21:59 ` Ruediger Meier
0 siblings, 1 reply; 18+ messages in thread
From: J William Piggott @ 2017-06-27 19:08 UTC (permalink / raw)
To: Rüdiger Meier, util-linux
On 06/27/2017 12:35 PM, Rüdiger Meier wrote:
>
>
> On 06/27/2017 05:12 PM, J William Piggott wrote:
>> On 06/27/2017 09:26 AM, Rüdiger Meier wrote:
>>> On 06/27/2017 02:42 PM, J William Piggott wrote:
>>>> On 06/26/2017 02:29 PM, Ruediger Meier wrote:
>>>>> From: Ruediger Meier <ruediger.meier@ga-group.nl>
>>>>> We change
>>>>>
>>>>>
>>>>> -h, --help display this help and exit
>>>>> -V, --version output version information and exit
>>>>>
>>>>> to
>>>>>
>>>>> -h, --help display this help
>>>>> -V, --version print version
>>>>>
>>>>> Some thoughts about this:
>>>>>
>>>>> * use "display" for --help because it matches better if we
>>>>> would add pager support (like git --help)
>>>>>
>>>>> * "print" for --version to be different
>>>>
>>>> To be different why?
>>>>
>>>
>>> Because AFAIR somewhere Karel or somebody else mentioned that we
>>> could add auto-pager support on terminal for long --help output
>>> (like findmnt) or otherwise colored help texts. This would be a
>>> difference, doing more than printf only.
>>
>> If I understand you correctly, using the word 'display' should imply
>> that a pager might be used?
>>
>> When reading open source documentation, messages, etc., I make
>> absolutely no distinction between: show, to stdout, display, print,
>> or output; to me they are absolute synonyms unless there is
>> additional language stating otherwise; such as:
>>
>
> Maybe I make this difference between display and print because there
> is a *print*() function in almost any programming language I know.
> But *display*() or *show*() are usually only known in any graphical
> libraries (widget toolkits, plotting, etc.).
Okay, I get that. It seems that there is a conflict between what makes
sense to a programmer, and what makes sense to a user.
How about this: programmatically print is ambiguous also. It can be
print to file, var, screen. So your associating the term 'display' with
gui tools should create a connection to the display device. I think that
is the goal here. A one-word term that connects an action with a device.
>
> BTW regarding show, see
>
> --status don't output anything, status code shows success
> So something can be "shown" without any output at all ;)
Show, would not be my first choice. The reason I favor 'display' is
because it is a synonym for a terminal monitor. So using it as a verb
hints at the intended target device. It also avoids the ambiguity as to
whether 'print' means 'print to screen', 'print to printer', or perhaps
something else. Same problem with 'output'. I think most, programmers
and users, would interpret 'display' as being sent to the display device
(pager or not). For conciseness in places like usage(), display is an
attempt to imply the device. I don't think any of the other synonyms can
do that.
>>> --version just print and exit
>>>
>>> --help display something and keep the display (pager) open.
>>>
>>
>> With this additional language it makes no difference for us whether
>> we use the same term, print or display, in both statements. But to a
>> new student of open source using different terms changes the meaning;
>> or at the very least is ambiguous. They may wonder: there must be a
>> reason they are using these different terms; what is it?
>>
>>>> It makes it sound like help and version will not have the same
>>>> action. Laymen think 'print' means send to the printer.
>>>>
>>>> Translators will have to figure out which different words to use.
>>>
>>> Hehe, I have never thought about printers. But for my bad English
>>> "display" sounds more like TV show or graphical X-display. ;)
>>>
>>> Seriously IMO "print" is the right term for command-line and shell
>>> environment . It's also more often used than "display" in POSIX and
>>> coreutils manpages.
>>
>> Using the term 'print' is residue from the days when a printer was
>> the only human readable output. I think it is unfortunate that it
>> has now become synonymous with sending output to the terminal display
>> monitor.
>>
>> However, whatever the consensus is for the best term, all I'm hoping
>> for is to use it consistently instead of all the other synonyms.
>>
>>>> What is broken by:
>>>>
>>>> -h, --help display this help
>>>> -V, --version display version
>>>>
>>>>
>>>> I really think it is a good idea to use consistent language for
>>>
>>> Consistent language is not always human-friendly
>>>
>>
>> For comprehension of technical material, consistency is not only
>> more human-friendly, it is imperative.
>>
>>> and can also be more hard or boring to read. See
>>
>> We are not talking about a novel. Technical material by necessity is
>> boring to read (unless you are enthusiastic about learning). Think
>> textbooks.
>>
>
> Yes, but I find my eyes are more relaxed when not everything looks
> like the same pattern with minor differences. Worst case example:
>
>
> --show-file-size display the size of the file
> --show-link-size display the size of the link
> --show-file-color display the color of the file
> --show-link-color display the color of the link
> --show-file-taste display the taste of the file
> --show-link-taste display the taste of the link
>
> This makes me ill. So I don't like to read the term "display" or
> "print" 20 times on the same screen. The --help and --version options
> are boring enough already. I see no problem mixing print and display
> there.
>
> A bit reordering and rewording makes it better:
>
>
> --show-file-size display the size of the file
> --show-file-color display the color of the file
> --show-file-taste display the taste of the file
> --show-link-size print link size
> --show-link-color print link color
> --show-link-taste print link taste
>
I understand your position. Personally, I think being ambiguous to gain
readability is a poor trade off for technical information. The above
implies that there is something different between the first three and
the last three.
>>>> comparable actions. It is easier to comprehend, especially for
>>>> non-native speakers. Once they understand the meaning of a term,
>>>> possibly from a context that they the understand well, then that
>>>> knowledge is transferable to other contexts. Why add confusion by
>>>> constantly interchanging term synonyms?
>>>>
>>>
>>> Anyways, I'm also fine with display. This was just my favorite
>>> proposal.
>>>
>>
>> I know when it comes to docs and strings that there is a long
>> tradition for hackers interjecting humor, wisecracks and generally
>> not taking things to seriously. I'm generally of that mindset
>> myself. However, it wasn't so long ago when I began using Linux that
>> I cannot remember being confused by all of the interchanging of
>> synonyms. Promoting this idea of using consistent language doesn't
>> matter that much to me personally, I'm trying to help new students.
>
> FYI I just investigated the coreutils history. They changed their
> strings the last time in 1993. Maybe that's also kind of consistent
> in tradition.
>
>
> This was their change 24 years ago
>
> - --help provide this help\n\
> - --version show program version\n");
>
> + --help display this help and exit\n\
> + --version output version information and exit\n");
>
That's an interesting change. I don't know that I'd call it an
improvement. I wonder if they went through the same discussions as we
are.
> Grepping all their manpages shows that they are using "display" almost
> only in this single help string, normally using "print" and sometimes
> "show".
>
> In their real (info) documentation they use:
>
> `--help'
> Print a usage message listing all available options, then exit
> successfully.
>
> `--version'
> Print the version number, then exit successfully.
>
At least they used 'print' in both of them. Although I don't love the
term 'print', my goal would be met if it was just used consistently.
Well, can see why this as never been addressed. If two people cannot
come to a consensus, than how will the project as a whole, or the entire
open source community. I guess I'll leave this can-of-worms alone and
agree to disagree.
>
> I think these ones would fit also for our manpages. I like their
> statement "listing *all* available options". It was not always clear
> to me whether
>
> or not I should hide unimportant/redundant options from --help output.
>
> cu, Rudi
>
>> I also have the impression that many of us are working to make open
>> source polished and professional. I believe that technical writing
>>
>> should be focused on comprehension and that using consistent
>> language, especially for terms, is imperative to that end.
> -- To unsubscribe from this list: send the line "unsubscribe
> util-linux" in
>
> the body of a message to majordomo@vger.kernel.org
>
> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
>
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 6/6] misc: update --help content again
2017-06-27 19:08 ` J William Piggott
@ 2017-06-28 21:59 ` Ruediger Meier
2017-07-28 13:34 ` J William Piggott
0 siblings, 1 reply; 18+ messages in thread
From: Ruediger Meier @ 2017-06-28 21:59 UTC (permalink / raw)
To: J William Piggott; +Cc: util-linux
On Tuesday 27 June 2017, J William Piggott wrote:
> On 06/27/2017 12:35 PM, Rüdiger Meier wrote:
> > On 06/27/2017 05:12 PM, J William Piggott wrote:
> >> On 06/27/2017 09:26 AM, Rüdiger Meier wrote:
> >>> On 06/27/2017 02:42 PM, J William Piggott wrote:
> >>>> On 06/26/2017 02:29 PM, Ruediger Meier wrote:
> >>>>> From: Ruediger Meier <ruediger.meier@ga-group.nl>
> >>>>> We change
> >>>>>
> >>>>>
> >>>>> -h, --help display this help and exit
> >>>>> -V, --version output version information and exit
> >>>>>
> >>>>> to
> >>>>>
> >>>>> -h, --help display this help
> >>>>> -V, --version print version
> >>>>>
> >>>>> Some thoughts about this:
> >>>>>
> >>>>> * use "display" for --help because it matches better if we
> >>>>> would add pager support (like git --help)
> >>>>>
> >>>>> * "print" for --version to be different
> >>>>
> >>>> To be different why?
> >>>
> >>> Because AFAIR somewhere Karel or somebody else mentioned that we
> >>> could add auto-pager support on terminal for long --help output
> >>> (like findmnt) or otherwise colored help texts. This would be a
> >>> difference, doing more than printf only.
> >>
> >> If I understand you correctly, using the word 'display' should
> >> imply that a pager might be used?
> >>
> >> When reading open source documentation, messages, etc., I make
> >> absolutely no distinction between: show, to stdout, display,
> >> print, or output; to me they are absolute synonyms unless there is
> >> additional language stating otherwise; such as:
> >
> > Maybe I make this difference between display and print because
> > there is a *print*() function in almost any programming language I
> > know. But *display*() or *show*() are usually only known in any
> > graphical libraries (widget toolkits, plotting, etc.).
>
> Okay, I get that. It seems that there is a conflict between what
> makes sense to a programmer, and what makes sense to a user.
>
> How about this: programmatically print is ambiguous also. It can be
> print to file, var, screen. So your associating the term 'display'
> with gui tools should create a connection to the display device. I
> think that is the goal here. A one-word term that connects an action
> with a device.
>
> > BTW regarding show, see
> >
> > --status don't output anything, status code shows success
> > So something can be "shown" without any output at all ;)
>
> Show, would not be my first choice. The reason I favor 'display' is
> because it is a synonym for a terminal monitor. So using it as a verb
> hints at the intended target device. It also avoids the ambiguity as
> to whether 'print' means 'print to screen', 'print to printer', or
> perhaps something else. Same problem with 'output'. I think most,
> programmers and users, would interpret 'display' as being sent to the
> display device (pager or not). For conciseness in places like
> usage(), display is an attempt to imply the device. I don't think any
> of the other synonyms can do that.
>
> >>> --version just print and exit
> >>>
> >>> --help display something and keep the display (pager) open.
> >>
> >> With this additional language it makes no difference for us
> >> whether we use the same term, print or display, in both
> >> statements. But to a new student of open source using different
> >> terms changes the meaning; or at the very least is ambiguous.
> >> They may wonder: there must be a reason they are using these
> >> different terms; what is it?
> >>
> >>>> It makes it sound like help and version will not have the same
> >>>> action. Laymen think 'print' means send to the printer.
> >>>>
> >>>> Translators will have to figure out which different words to
> >>>> use.
> >>>
> >>> Hehe, I have never thought about printers. But for my bad
> >>> English "display" sounds more like TV show or graphical
> >>> X-display. ;)
> >>>
> >>> Seriously IMO "print" is the right term for command-line and
> >>> shell environment . It's also more often used than "display" in
> >>> POSIX and coreutils manpages.
> >>
> >> Using the term 'print' is residue from the days when a printer was
> >> the only human readable output. I think it is unfortunate that it
> >> has now become synonymous with sending output to the terminal
> >> display monitor.
> >>
> >> However, whatever the consensus is for the best term, all I'm
> >> hoping for is to use it consistently instead of all the other
> >> synonyms.
> >>
> >>>> What is broken by:
> >>>>
> >>>> -h, --help display this help
> >>>> -V, --version display version
> >>>>
> >>>>
> >>>> I really think it is a good idea to use consistent language for
> >>>
> >>> Consistent language is not always human-friendly
> >>
> >> For comprehension of technical material, consistency is not only
> >> more human-friendly, it is imperative.
> >>
> >>> and can also be more hard or boring to read. See
> >>
> >> We are not talking about a novel. Technical material by necessity
> >> is boring to read (unless you are enthusiastic about learning).
> >> Think textbooks.
> >
> > Yes, but I find my eyes are more relaxed when not everything looks
> > like the same pattern with minor differences. Worst case example:
> >
> >
> > --show-file-size display the size of the file
> > --show-link-size display the size of the link
> > --show-file-color display the color of the file
> > --show-link-color display the color of the link
> > --show-file-taste display the taste of the file
> > --show-link-taste display the taste of the link
> >
> > This makes me ill. So I don't like to read the term "display" or
> > "print" 20 times on the same screen. The --help and --version
> > options are boring enough already. I see no problem mixing print
> > and display there.
> >
> > A bit reordering and rewording makes it better:
> >
> >
> > --show-file-size display the size of the file
> > --show-file-color display the color of the file
> > --show-file-taste display the taste of the file
> > --show-link-size print link size
> > --show-link-color print link color
> > --show-link-taste print link taste
>
> I understand your position. Personally, I think being ambiguous to
> gain readability is a poor trade off for technical information. The
> above implies that there is something different between the first
> three and the last three.
>
> >>>> comparable actions. It is easier to comprehend, especially for
> >>>> non-native speakers. Once they understand the meaning of a
> >>>> term, possibly from a context that they the understand well,
> >>>> then that knowledge is transferable to other contexts. Why add
> >>>> confusion by constantly interchanging term synonyms?
> >>>
> >>> Anyways, I'm also fine with display. This was just my favorite
> >>> proposal.
> >>
> >> I know when it comes to docs and strings that there is a long
> >> tradition for hackers interjecting humor, wisecracks and generally
> >> not taking things to seriously. I'm generally of that mindset
> >> myself. However, it wasn't so long ago when I began using Linux
> >> that I cannot remember being confused by all of the interchanging
> >> of synonyms. Promoting this idea of using consistent language
> >> doesn't matter that much to me personally, I'm trying to help new
> >> students.
> >
> > FYI I just investigated the coreutils history. They changed their
> > strings the last time in 1993. Maybe that's also kind of
> > consistent in tradition.
> >
> >
> > This was their change 24 years ago
> >
> > - --help provide this help\n\
> > - --version show program version\n");
> >
> > + --help display this help and exit\n\
> > + --version output version information and exit\n");
>
> That's an interesting change. I don't know that I'd call it an
> improvement. I wonder if they went through the same discussions as we
> are.
Hehe, my major point was, that it's actually stupid that we discuss
about this at all. (Probably that's why nobody else joined the
discusson ;) Venerable coreutils developers came to a *final* decision
24(!) years ago and never changed it since then! *We* where using the
*same* strings already, translations too, no complaints ever. Why do we
touch this at all? Why not accept the state? It's almost blasphemy to
impeach these strings. ;)
util-linux plus coreutils would mean about more than 200 comands on a
usual Linux system would use the same style (consensus!). Other
projects also follow coreutils when thinking about CLI style.
Anyways ... I'm really happy that our strings are quite shorter now. If
you wouldn't have started to change the strings then I wouldn't have
done anything. My only real complaints about your original change were:
1. Why change at all?
2. Why remove "this"?
3. If change, why not at least shorter?
;)
> > Grepping all their manpages shows that they are using "display"
> > almost only in this single help string, normally using "print" and
> > sometimes "show".
> >
> > In their real (info) documentation they use:
> >
> > `--help'
> > Print a usage message listing all available options, then exit
> > successfully.
> >
> > `--version'
> > Print the version number, then exit successfully.
>
> At least they used 'print' in both of them. Although I don't love the
> term 'print', my goal would be met if it was just used consistently.
>
> Well, can see why this as never been addressed. If two people cannot
> come to a consensus, than how will the project as a whole, or the
> entire open source community. I guess I'll leave this can-of-worms
> alone and agree to disagree.
>
> > I think these ones would fit also for our manpages. I like their
> > statement "listing *all* available options". It was not always
> > clear to me whether
> >
> > or not I should hide unimportant/redundant options from --help
> > output.
> >
> > cu, Rudi
> >
> >> I also have the impression that many of us are working to make
> >> open source polished and professional. I believe that technical
> >> writing
> >>
> >> should be focused on comprehension and that using consistent
> >> language, especially for terms, is imperative to that end.
> >
> > -- To unsubscribe from this list: send the line "unsubscribe
> > util-linux" in
> >
> > the body of a message to majordomo@vger.kernel.org
> >
> > More majordomo info at http://vger.kernel.org/majordomo-info.html
>
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux"
> in the body of a message to majordomo@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 6/6] misc: update --help content again
2017-06-28 21:59 ` Ruediger Meier
@ 2017-07-28 13:34 ` J William Piggott
0 siblings, 0 replies; 18+ messages in thread
From: J William Piggott @ 2017-07-28 13:34 UTC (permalink / raw)
To: Ruediger Meier; +Cc: util-linux
On 06/28/2017 05:59 PM, Ruediger Meier wrote:
> On Tuesday 27 June 2017, J William Piggott wrote:
>> On 06/27/2017 12:35 PM, Rüdiger Meier wrote:
>>> On 06/27/2017 05:12 PM, J William Piggott wrote:
>>>> On 06/27/2017 09:26 AM, Rüdiger Meier wrote:
>>>>> On 06/27/2017 02:42 PM, J William Piggott wrote:
>>>>>> On 06/26/2017 02:29 PM, Ruediger Meier wrote:
>>>>>>> From: Ruediger Meier <ruediger.meier@ga-group.nl>
>>>>>>> We change
>>>>>>>
>>>>>>>
>>>>>>> -h, --help display this help and exit
>>>>>>> -V, --version output version information and exit
>>>>>>>
>>>>>>> to
>>>>>>>
>>>>>>> -h, --help display this help
>>>>>>> -V, --version print version
>>>>>>>
>>>>>>> Some thoughts about this:
>>>>>>>
>>>>>>> * use "display" for --help because it matches better if we
>>>>>>> would add pager support (like git --help)
>>>>>>>
>>>>>>> * "print" for --version to be different
>>>>>>
>>>>>> To be different why?
>>>>>
>>>>> Because AFAIR somewhere Karel or somebody else mentioned that we
>>>>> could add auto-pager support on terminal for long --help output
>>>>> (like findmnt) or otherwise colored help texts. This would be a
>>>>> difference, doing more than printf only.
>>>>
>>>> If I understand you correctly, using the word 'display' should
>>>> imply that a pager might be used?
>>>>
>>>> When reading open source documentation, messages, etc., I make
>>>> absolutely no distinction between: show, to stdout, display,
>>>> print, or output; to me they are absolute synonyms unless there is
>>>> additional language stating otherwise; such as:
>>>
>>> Maybe I make this difference between display and print because
>>> there is a *print*() function in almost any programming language I
>>> know. But *display*() or *show*() are usually only known in any
>>> graphical libraries (widget toolkits, plotting, etc.).
>>
>> Okay, I get that. It seems that there is a conflict between what
>> makes sense to a programmer, and what makes sense to a user.
>>
>> How about this: programmatically print is ambiguous also. It can be
>> print to file, var, screen. So your associating the term 'display'
>> with gui tools should create a connection to the display device. I
>> think that is the goal here. A one-word term that connects an action
>> with a device.
>>
>>> BTW regarding show, see
>>>
>>> --status don't output anything, status code shows success
>>> So something can be "shown" without any output at all ;)
>>
>> Show, would not be my first choice. The reason I favor 'display' is
>> because it is a synonym for a terminal monitor. So using it as a verb
>> hints at the intended target device. It also avoids the ambiguity as
>> to whether 'print' means 'print to screen', 'print to printer', or
>> perhaps something else. Same problem with 'output'. I think most,
>> programmers and users, would interpret 'display' as being sent to the
>> display device (pager or not). For conciseness in places like
>> usage(), display is an attempt to imply the device. I don't think any
>> of the other synonyms can do that.
>>
>>>>> --version just print and exit
>>>>>
>>>>> --help display something and keep the display (pager) open.
>>>>
>>>> With this additional language it makes no difference for us
>>>> whether we use the same term, print or display, in both
>>>> statements. But to a new student of open source using different
>>>> terms changes the meaning; or at the very least is ambiguous.
>>>> They may wonder: there must be a reason they are using these
>>>> different terms; what is it?
>>>>
>>>>>> It makes it sound like help and version will not have the same
>>>>>> action. Laymen think 'print' means send to the printer.
>>>>>>
>>>>>> Translators will have to figure out which different words to
>>>>>> use.
>>>>>
>>>>> Hehe, I have never thought about printers. But for my bad
>>>>> English "display" sounds more like TV show or graphical
>>>>> X-display. ;)
>>>>>
>>>>> Seriously IMO "print" is the right term for command-line and
>>>>> shell environment . It's also more often used than "display" in
>>>>> POSIX and coreutils manpages.
>>>>
>>>> Using the term 'print' is residue from the days when a printer was
>>>> the only human readable output. I think it is unfortunate that it
>>>> has now become synonymous with sending output to the terminal
>>>> display monitor.
>>>>
>>>> However, whatever the consensus is for the best term, all I'm
>>>> hoping for is to use it consistently instead of all the other
>>>> synonyms.
>>>>
>>>>>> What is broken by:
>>>>>>
>>>>>> -h, --help display this help
>>>>>> -V, --version display version
>>>>>>
>>>>>>
>>>>>> I really think it is a good idea to use consistent language for
>>>>>
>>>>> Consistent language is not always human-friendly
>>>>
>>>> For comprehension of technical material, consistency is not only
>>>> more human-friendly, it is imperative.
>>>>
>>>>> and can also be more hard or boring to read. See
>>>>
>>>> We are not talking about a novel. Technical material by necessity
>>>> is boring to read (unless you are enthusiastic about learning).
>>>> Think textbooks.
>>>
>>> Yes, but I find my eyes are more relaxed when not everything looks
>>> like the same pattern with minor differences. Worst case example:
>>>
>>>
>>> --show-file-size display the size of the file
>>> --show-link-size display the size of the link
>>> --show-file-color display the color of the file
>>> --show-link-color display the color of the link
>>> --show-file-taste display the taste of the file
>>> --show-link-taste display the taste of the link
>>>
>>> This makes me ill. So I don't like to read the term "display" or
>>> "print" 20 times on the same screen. The --help and --version
>>> options are boring enough already. I see no problem mixing print
>>> and display there.
>>>
>>> A bit reordering and rewording makes it better:
>>>
>>>
>>> --show-file-size display the size of the file
>>> --show-file-color display the color of the file
>>> --show-file-taste display the taste of the file
>>> --show-link-size print link size
>>> --show-link-color print link color
>>> --show-link-taste print link taste
>>
>> I understand your position. Personally, I think being ambiguous to
>> gain readability is a poor trade off for technical information. The
>> above implies that there is something different between the first
>> three and the last three.
>>
>>>>>> comparable actions. It is easier to comprehend, especially for
>>>>>> non-native speakers. Once they understand the meaning of a
>>>>>> term, possibly from a context that they the understand well,
>>>>>> then that knowledge is transferable to other contexts. Why add
>>>>>> confusion by constantly interchanging term synonyms?
>>>>>
>>>>> Anyways, I'm also fine with display. This was just my favorite
>>>>> proposal.
>>>>
>>>> I know when it comes to docs and strings that there is a long
>>>> tradition for hackers interjecting humor, wisecracks and generally
>>>> not taking things to seriously. I'm generally of that mindset
>>>> myself. However, it wasn't so long ago when I began using Linux
>>>> that I cannot remember being confused by all of the interchanging
>>>> of synonyms. Promoting this idea of using consistent language
>>>> doesn't matter that much to me personally, I'm trying to help new
>>>> students.
>>>
>>> FYI I just investigated the coreutils history. They changed their
>>> strings the last time in 1993. Maybe that's also kind of
>>> consistent in tradition.
>>>
>>>
>>> This was their change 24 years ago
>>>
>>> - --help provide this help\n\
>>> - --version show program version\n");
>>>
>>> + --help display this help and exit\n\
>>> + --version output version information and exit\n");
>>
>> That's an interesting change. I don't know that I'd call it an
>> improvement. I wonder if they went through the same discussions as we
>> are.
>
> Hehe, my major point was, that it's actually stupid that we discuss
> about this at all. (Probably that's why nobody else joined the
> discusson ;) Venerable coreutils developers came to a *final* decision
> 24(!) years ago and never changed it since then! *We* where using the
> *same* strings already, translations too, no complaints ever. Why do we
> touch this at all? Why not accept the state? It's almost blasphemy to
> impeach these strings. ;)
>
> util-linux plus coreutils would mean about more than 200 comands on a
> usual Linux system would use the same style (consensus!). Other
> projects also follow coreutils when thinking about CLI style.
>
> Anyways ... I'm really happy that our strings are quite shorter now. If
> you wouldn't have started to change the strings then I wouldn't have
> done anything.
It gets quiet around here when the Chief is gone. So I'll drag up this old
debate again. I know that I'm violating Karel's "tattoo" directive, but my
brain was tattooed with: "any job worth doing, is worth doing right"; by
generations of old-world craftsmen.
> My only real complaints about your original change were:
>
> 1. Why change at all?
> 2. Why remove "this"?
> 3. If change, why not at least shorter?
Perhaps your enumerated list was meant to be rhetorical, but I'll reply
anyway.
3. because I thought someone would complain; I'm all for conciseness
2. I could make a case for this, but it would only distract from my goal
1. to remove the ambiguity of using different verbs for the same action
For us to progress in this discussion I think we need to begin anew
with the basics of any writing assignment: define the subject matter,
target audience, and writing style.
I define them as such:
Subject Matter: User Guides
Target Audience: Users
Writing Style: Technical Writing
My impression is that you define them as:
Subject Matter: Entertainment
Target Audience: CS degree or equivalent
Writing Style: Creative Writing
I have that impression because you argue that:
* consistency is boring
* 'print' is the correct term because all programming languages use it
Being consistent is not merely my opinion. Writing concisely, clearly,
and unambiguously, consistently using well defined key terms, are all
fundamental principals of Technical Writing.
It is unnecessary to assume preexisting knowledge when writing man pages
or help output. If we're going to spend our valuable time writing
documentation it should be for the largest possible target audience. Users
do not know that programmatically 'print' functions send something to
stdout; or even what stdout is. Everyone will understand what 'display'
means, even though programmers may find it an odd choice.
I labeled the Subject Matter as 'User guides' because that is a specific
category of Technical Writing and that is what this material is.
I'm not asking that the project improve consistency for my sake. I'm
asking, perhaps, for some underprivileged kid trying to bootstrap their
life by learning Linux on a 486 that they found in the rubbish.
I believe that in every discussion we've had so far, I have compromised
in your favor. Since you have stated, more than once I think, that you
have no strong opinion on this, how about a little charity in the name
of compromise and allow these two options, with the same action, to use
the same verb? Then people without a CS degree might have a better shot
at understanding them.
>
> ;)
>
>>> Grepping all their manpages shows that they are using "display"
>>> almost only in this single help string, normally using "print" and
>>> sometimes "show".
>>>
>>> In their real (info) documentation they use:
>>>
>>> `--help'
>>> Print a usage message listing all available options, then exit
>>> successfully.
>>>
>>> `--version'
>>> Print the version number, then exit successfully.
>>
>> At least they used 'print' in both of them. Although I don't love the
>> term 'print', my goal would be met if it was just used consistently.
>>
>> Well, can see why this as never been addressed. If two people cannot
>> come to a consensus, than how will the project as a whole, or the
>> entire open source community. I guess I'll leave this can-of-worms
>> alone and agree to disagree.
>>
>>> I think these ones would fit also for our manpages. I like their
>>> statement "listing *all* available options". It was not always
>>> clear to me whether or not I should hide unimportant/redundant
>>> options from --help output.
>>>
>>> cu, Rudi
>>>
>>>> I also have the impression that many of us are working to make
>>>> open source polished and professional. I believe that technical
>>>> writing should be focused on comprehension and that using consistent
>>>> language, especially for terms, is imperative to that end.
>>>
>>> -- To unsubscribe from this list: send the line "unsubscribe
>>> util-linux" in
>>>
>>> the body of a message to majordomo@vger.kernel.org
>>>
>>> More majordomo info at http://vger.kernel.org/majordomo-info.html
>>
>> --
>> To unsubscribe from this list: send the line "unsubscribe util-linux"
>> in the body of a message to majordomo@vger.kernel.org
>> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
>
> --
> To unsubscribe from this list: send the line "unsubscribe util-linux" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
^ permalink raw reply [flat|nested] 18+ messages in thread
end of thread, other threads:[~2017-07-28 13:34 UTC | newest]
Thread overview: 18+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-06-26 18:29 [PATCH 0/6] consolidate help/version option descriptions Ruediger Meier
2017-06-26 18:29 ` [PATCH 1/6] misc: revert to the old USAGE_HELP strings Ruediger Meier
2017-06-26 18:29 ` [PATCH 2/6] misc: introduce PRINT_USAGE_HELP() Ruediger Meier
2017-06-27 9:46 ` Karel Zak
2017-06-27 10:48 ` Rüdiger Meier
2017-06-27 12:19 ` Karel Zak
2017-06-26 18:29 ` [PATCH 3/6] misc: consolidate all --help option descriptions Ruediger Meier
2017-06-26 18:29 ` [PATCH 4/6] blockdev: improve --help and man page Ruediger Meier
2017-06-26 18:29 ` [PATCH 5/6] login: add --help text Ruediger Meier
2017-06-26 18:29 ` [PATCH 6/6] misc: update --help content again Ruediger Meier
2017-06-27 12:42 ` J William Piggott
2017-06-27 13:26 ` Rüdiger Meier
2017-06-27 15:12 ` J William Piggott
2017-06-27 16:35 ` Rüdiger Meier
2017-06-27 19:08 ` J William Piggott
2017-06-28 21:59 ` Ruediger Meier
2017-07-28 13:34 ` J William Piggott
2017-06-27 9:49 ` [PATCH 0/6] consolidate help/version option descriptions Karel Zak
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.