doc: fix inconsistent capitalization in --help output

* src/base64.c (usage): Don't capitalize the first character
in an --option description.
* src/stdbuf.c (usage): Likewise.
* src/truncate.c (usage): Likewise.
* cfg.mk (sc_option_desc_uppercase): A new syntax check to
stop this happening in future.
* man/Makefile.am (sc_option_desc_uppercase): Ensure all
man pages are generated, then search for erroneous uppercase chars.
* src/Makefile.am (all_programs): Ensure all
commands are built so that all man pages can be generated.

6 files changed, 28 insertions, 7 deletions

diff --git a/cfg.mk b/cfg.mk
index b5a21c3fc..9c748e324 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -171,6 +171,15 @@ ALL_RECURSIVE_TARGETS += sc_check-AUTHORS
 sc_check-AUTHORS:
 	@$(MAKE) -C src $@
 
+# Option descriptions should not start with a capital letter
+# One could grep source directly as follows:
+# grep -E " {2,6}-.*[^.]  [A-Z][a-z]" $$($(VC_LIST_EXCEPT) | grep '\.c$$')
+# but that would miss descriptions not on the same line as the -option.
+ALL_RECURSIVE_TARGETS += sc_option_desc_uppercase
+sc_option_desc_uppercase:
+	@$(MAKE) -s -C src all_programs
+	@$(MAKE) -s -C man $@
+
 # Perl-based tests used to exec perl from a #!/bin/sh script.
 # Now they all start with #!/usr/bin/perl and the portability
 # infrastructure is in tests/Makefile.am.  Make sure no old-style
diff --git a/man/Makefile.am b/man/Makefile.am
index 904b302d0..7cebbf143 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -173,6 +173,13 @@ mapped_name = `echo $*|sed 's/^install$$/ginstall/; s/^test$$/[/'`
 	    ;;							\
 	esac
 
+# Option descriptions should not start with a capital letter
+.PHONY: sc_option_desc_uppercase
+sc_option_desc_uppercase: $(dist_man1_MANS) $(NO_INSTALL_PROGS_DEFAULT:%=%.1)
+	@grep '^\\fB\\-' -A1 *.1 | LC_ALL=C grep '\.1.[A-Z][a-z]' && \
+	    { echo 1>&2 '$(ME): found initial capitals in --help';   \
+	      exit 1; } || :;
+
 distcheck-hook: check-x-vs-1 check-programs-vs-x
 
 # Sort in traditional ASCII order, regardless of the current locale;
diff --git a/src/Makefile.am b/src/Makefile.am
index c73f7dc07..addc2eb19 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -642,6 +642,11 @@ all_programs.list:
 # install a binary, require that all programs be built at distribution time.
 dist-hook: $(all_programs)
 
+# Ensure that all programs are built so we can for example
+# subsequently syntax check all man pages.
+.PHONY: all_programs
+all_programs: $(all_programs)
+
 pm = progs-makefile
 pr = progs-readme
 # Ensure that the list of programs in README matches the list
diff --git a/src/base64.c b/src/base64.c
index ce58f2fdb..34569eca4 100644
--- a/src/base64.c
+++ b/src/base64.c
@@ -61,9 +61,9 @@ Usage: %s [OPTION]... [FILE]\n\
 Base64 encode or decode FILE, or standard input, to standard output.\n\
 \n"), program_name);
       fputs (_("\
-  -d, --decode          Decode data\n\
-  -i, --ignore-garbage  When decoding, ignore non-alphabet characters\n\
-  -w, --wrap=COLS       Wrap encoded lines after COLS character (default 76).\n\
+  -d, --decode          decode data\n\
+  -i, --ignore-garbage  when decoding, ignore non-alphabet characters\n\
+  -w, --wrap=COLS       wrap encoded lines after COLS character (default 76).\n\
                           Use 0 to disable line wrapping\n\
 \n\
 "), stdout);
diff --git a/src/stdbuf.c b/src/stdbuf.c
index de3f515aa..d9d6f17d0 100644
--- a/src/stdbuf.c
+++ b/src/stdbuf.c
@@ -98,9 +98,9 @@ Run COMMAND, with modified buffering operations for its standard streams.\n\
 Mandatory arguments to long options are mandatory for short options too.\n\
 "), stdout);
       fputs (_("\
-  -i, --input=MODE   Adjust standard input stream buffering\n\
-  -o, --output=MODE  Adjust standard output stream buffering\n\
-  -e, --error=MODE   Adjust standard error stream buffering\n\
+  -i, --input=MODE   adjust standard input stream buffering\n\
+  -o, --output=MODE  adjust standard output stream buffering\n\
+  -e, --error=MODE   adjust standard error stream buffering\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
diff --git a/src/truncate.c b/src/truncate.c
index 5085d2c0f..70573cc2f 100644
--- a/src/truncate.c
+++ b/src/truncate.c
@@ -117,7 +117,7 @@ Mandatory arguments to long options are mandatory for short options too.\n\
   -c, --no-create        do not create any files\n\
 "), stdout);
       fputs (_("\
-  -o, --io-blocks        Treat SIZE as number of IO blocks instead of bytes\n\
+  -o, --io-blocks        treat SIZE as number of IO blocks instead of bytes\n\
 "), stdout);
       fputs (_("\
   -r, --reference=FILE   use this FILE's size\n\