doc: enforce @var{lower} policy

* doc/coreutils.texi: Fix remaining violations.
* doc/Makefile.am (sc-lower-case-var): New rule.
Add some command-suppressing "@" directives so that a successful
"make check" run is less noisy.

2 files changed, 61 insertions, 42 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9d6997c78..cba333226 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -50,13 +50,14 @@ syntax_checks =		\
   sc-avoid-timezone	\
   sc-avoid-zeroes	\
   sc-exponent-grouping	\
+  sc-lower-case-var	\
   sc-use-small-caps-NUL
 
 .PHONY: $(syntax_checks) check-texinfo
 
 # List words/regexps here that should not appear in the texinfo documentation.
 check-texinfo: $(syntax_checks)
-	fail=0; \
+	@fail=0; \
 	grep '@url{' $(srcdir)/*.texi && fail=1; \
 	grep '\$$@"' $(srcdir)/*.texi && fail=1; \
 	grep -n '[^[:punct:]]@footnote' $(srcdir)/*.texi && fail=1; \
@@ -73,27 +74,45 @@ check-texinfo: $(syntax_checks)
 
 # Use `time zone', not `timezone'.
 sc-avoid-timezone:
-	$(EGREP) timezone $(srcdir)/*.texi && exit 1 || :
+	@$(EGREP) timezone $(srcdir)/*.texi && exit 1 || :
 
 # Check for insufficient exponent grouping, e.g.,
 # @math{2^64} should be @math{2^{64}}.
 sc-exponent-grouping:
-	$(EGREP) '\{.*\^[0-9][0-9]' $(srcdir)/*.texi && exit 1 || :
+	@$(EGREP) '\{.*\^[0-9][0-9]' $(srcdir)/*.texi && exit 1 || :
 
 # E.g., use @sc{nul}, not NUL.
 sc-use-small-caps-NUL:
-	$(EGREP) '$(_W)NUL$(W_)' $(srcdir)/*.texi && exit 1 || :
+	@$(EGREP) '$(_W)NUL$(W_)' $(srcdir)/*.texi && exit 1 || :
 
 # Say I/O, not IO.
 sc-avoid-io:
-	$(EGREP) '$(_W)IO$(W_)' $(srcdir)/*.texi && exit 1 || :
+	@$(EGREP) '$(_W)IO$(W_)' $(srcdir)/*.texi && exit 1 || :
 
 # I prefer nonzero over non-zero.
 sc-avoid-non-zero:
-	$(EGREP) non-zero $(srcdir)/*.texi && exit 1 || :
+	@$(EGREP) non-zero $(srcdir)/*.texi && exit 1 || :
 
 # Use `zeros', not `zeroes' (nothing wrong with `zeroes'. just be consistent).
 sc-avoid-zeroes:
-	$(EGREP) -i '$(_W)zeroes$(W_)' $(srcdir)/*.texi && exit 1 || :
+	@$(EGREP) -i '$(_W)zeroes$(W_)' $(srcdir)/*.texi && exit 1 || :
+
+# ME = $(subdir)/$(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST))
+ME = doc/Makefile
+
+# The quantity inside @var{...} should not contain upper case letters.
+# The leading backslash exemption is to permit in-macro uses like
+# @var{\varName\} where the upper case letter is part of a parameter name.
+find_upper_case_var =		\
+  '/\@var{/ or next;		\
+   while (/\@var{(.+?)}/g)	\
+     {				\
+       $$v = $$1;		\
+       $$v =~ /[A-Z]/ && $$v !~ /^\\/ and (print "$$ARGV:$$.:$$_"), $$m = 1 \
+     }				\
+   END {$$m and (warn "$(ME): do not use upper case in \@var{...}\n"), exit 1}'
+sc-lower-case-var:
+	@$(PERL) -e 1 2> /dev/null && \
+	  $(PERL) -lne $(find_upper_case_var) $(srcdir)/*.texi
 
 check: check-texinfo
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 8dc818993..e3311681e 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -2024,13 +2024,13 @@ The program accepts the following options.  Also see @ref{Common options}.
 
 @table @samp
 
-@item -w @var{COLS}
-@itemx --wrap=@var{COLS}
+@item -w @var{cols}
+@itemx --wrap=@var{cols}
 @opindex -w
 @opindex --wrap
 @cindex wrap data
 @cindex column to wrap data after
-During encoding, wrap lines after @var{COLS} characters.  This must be
+During encoding, wrap lines after @var{cols} characters.  This must be
 a positive number.
 
 The default is to wrap after 76 characters.  Use the value 0 to
@@ -2353,8 +2353,8 @@ is 8).
 Use a form feed instead of newlines to separate output pages.  This does
 not alter the default page length of 66 lines.
 
-@item -h @var{HEADER}
-@itemx --header=@var{HEADER}
+@item -h @var{header}
+@itemx --header=@var{header}
 @opindex -h
 @opindex --header
 Replace the file name in the header with the centered string @var{header}.
@@ -2424,11 +2424,11 @@ first line of the input file (not the first line printed, compare the
 Optional argument @var{number-separator} is the character appended to
 the line number to separate it from the text followed.  The default
 separator is the TAB character.  In a strict sense a TAB is always
-printed with single column output only.  The @var{TAB}-width varies
-with the @var{TAB}-position, e.g., with the left @var{margin} specified
+printed with single column output only.  The @var{tab}-width varies
+with the @var{tab}-position, e.g., with the left @var{margin} specified
 by @option{-o} option.  With multicolumn output priority is given to
 @samp{equal width of output columns} (a @acronym{POSIX} specification).
-The @var{TAB}-width is fixed to the value of the first column and does
+The @var{tab}-width is fixed to the value of the first column and does
 not change with different values of left @var{margin}.  That means a
 fixed number of spaces is always printed in the place of the
 @var{number-separator tab}.  The tabification depends upon the output
@@ -3267,16 +3267,16 @@ Print only the maximum line lengths.
 @c texi2dvi (GNU Texinfo 4.11) 1.104
 @c @cindex including files from @command{\cmd\}
 Disallow processing files named on the command line, and instead process
-those named in file @var{file}; each name being terminated by a NUL byte.
+those named in file @var{file}; each name being terminated by a @sc{nul} byte.
 This is useful \withTotalOption\
 when the list of file names is so long that it may exceed a command line
 length limitation.
 In such cases, running @command{\cmd\} via @command{xargs} is undesirable
 because it splits the list into pieces and makes @command{\cmd\} print
 \subListOutput\ for each sublist rather than for the entire list.
-One way to produce a list of NUL terminated file names is with @sc{gnu}
+One way to produce a list of @sc{nul} terminated file names is with @sc{gnu}
 @command{find}, using its @option{-print0} predicate.
-If @var{file} is @samp{-} then the NUL terminated file names
+If @var{file} is @samp{-} then the @sc{nul} terminated file names
 are read from standard input.
 @end macro
 @filesZeroFromOption{wc,,a total}
@@ -4363,8 +4363,8 @@ and the command @samp{shuf -i 1-4} might output:
 @noindent
 These examples all have four input lines, so @command{shuf} might
 produce any of the twenty-four possible permutations of the input.  In
-general, if there are @var{N} input lines, there are @var{N}! (i.e.,
-@var{N} factorial, or @var{N} * (@var{N} - 1) * @dots{} * 1) possible
+general, if there are @var{n} input lines, there are @var{n}! (i.e.,
+@var{n} factorial, or @var{n} * (@var{n} - 1) * @dots{} * 1) possible
 output permutations.
 
 @exitstatus
@@ -6270,7 +6270,7 @@ the main output:
 @end example
 
 @noindent
-The @var{begN} and @var{endN} are unsigned integers that record the
+The @var{begn} and @var{endn} are unsigned integers that record the
 byte position of the beginning and end of each file name in the output.
 This makes it easy for Emacs to find the names, even when they contain
 unusual characters such as space or newline, without fancy searching.
@@ -8416,11 +8416,11 @@ The program accepts the following options.  Also see @ref{Common options}.
 @cindex force deletion
 Override file permissions if necessary to allow overwriting.
 
-@item -@var{NUMBER}
-@itemx -n @var{NUMBER}
-@itemx --iterations=@var{NUMBER}
-@opindex -n @var{NUMBER}
-@opindex --iterations=@var{NUMBER}
+@item -@var{number}
+@itemx -n @var{number}
+@itemx --iterations=@var{number}
+@opindex -n @var{number}
+@opindex --iterations=@var{number}
 @cindex iterations, selecting the number of
 By default, @command{shred} uses 25 passes of overwrite.  This is enough
 for all of the useful overwrite patterns to be used at least once.
@@ -8433,13 +8433,13 @@ time to waste.
 Use @var{file} as a source of random data used to overwrite and to
 choose pass ordering.  @xref{Random sources}.
 
-@item -s @var{BYTES}
-@itemx --size=@var{BYTES}
-@opindex -s @var{BYTES}
-@opindex --size=@var{BYTES}
+@item -s @var{bytes}
+@itemx --size=@var{bytes}
+@opindex -s @var{bytes}
+@opindex --size=@var{bytes}
 @cindex size of file to shred
-Shred the first @var{BYTES} bytes of the file.  The default is to shred
-the whole file.  @var{BYTES} can be followed by a size specification like
+Shred the first @var{bytes} bytes of the file.  The default is to shred
+the whole file.  @var{bytes} can be followed by a size specification like
 @samp{K}, @samp{M}, or @samp{G} to specify a multiple.  @xref{Block size}.
 
 @item -u
@@ -9684,10 +9684,10 @@ the origin for any relative @var{time}s given, but is otherwise ignored.
 For example, @samp{-r foo -d '-5 seconds'} specifies a time stamp
 equal to five seconds before the corresponding time stamp for @file{foo}.
 
-@item -t [[@var{CC}]@var{YY}]@var{MMDDhhmm}[.@var{ss}]
+@item -t [[@var{cc}]@var{yy}]@var{mmddhhmm}[.@var{ss}]
 Use the argument (optional four-digit or two-digit years, months,
 days, hours, minutes, optional seconds) instead of the current time.
-If the year is specified with only two digits, then @var{CC}
+If the year is specified with only two digits, then @var{cc}
 is 20 for years in the range 0 @dots{} 68, and 19 for years in
 69 @dots{} 99.  If no digits of the year are specified,
 the argument is interpreted as a date in the current year.
@@ -9698,8 +9698,8 @@ the argument is interpreted as a date in the current year.
 On older systems, @command{touch} supports an obsolete syntax, as follows.
 If no timestamp is given with any of the @option{-d}, @option{-r}, or
 @option{-t} options, and if there are two or more @var{file}s and the
-first @var{file} is of the form @samp{@var{MMDDhhmm}[@var{YY}]} and this
-would be a valid argument to the @option{-t} option (if the @var{YY}, if
+first @var{file} is of the form @samp{@var{mmddhhmm}[@var{yy}]} and this
+would be a valid argument to the @option{-t} option (if the @var{yy}, if
 any, were moved to the front), and if the represented year
 is in the range 1969--1999, that argument is interpreted as the time
 for the other files instead of as a file name.
@@ -10079,8 +10079,8 @@ This option is equivalent to @option{--block-size=1M}.
 For each symbolic links encountered by @command{du},
 consider the disk space used by the symbolic link.
 
-@item --max-depth=@var{DEPTH}
-@opindex --max-depth=@var{DEPTH}
+@item --max-depth=@var{depth}
+@opindex --max-depth=@var{depth}
 @cindex limiting output of @command{du}
 Show the total for each directory (and file if --all) that is at
 most MAX_DEPTH levels down from the root of the hierarchy.  The root
@@ -10189,10 +10189,10 @@ begins with @samp{posix-} the @samp{posix-} is ignored; and if
 Skip directories that are on different file systems from the one that
 the argument being processed is on.
 
-@item --exclude=@var{PATTERN}
-@opindex --exclude=@var{PATTERN}
+@item --exclude=@var{pattern}
+@opindex --exclude=@var{pattern}
 @cindex excluding files from @command{du}
-When recursing, skip subdirectories or files matching @var{PATTERN}.
+When recursing, skip subdirectories or files matching @var{pattern}.
 For example, @code{du --exclude='*.o'} excludes files whose names
 end in @samp{.o}.
 
@@ -14543,7 +14543,7 @@ If @var{pid} is not positive, a system-dependent set of system
 processes is excluded from the list of processes to which the signal
 is sent.
 
-If a negative @var{PID} argument is desired as the first one, it
+If a negative @var{pid} argument is desired as the first one, it
 should be preceded by @option{--}.  However, as a common extension to
 @acronym{POSIX}, @option{--} is not required with @samp{kill
 -@var{signal} -@var{pid}}.  The following commands are equivalent: