Re: du --files-from feature request

[Jim Meyering]

Pádraig Brady <address@hidden> wrote:
> I also did a non user visible change to the info docs while I was
> at it to standardize on using lower-case @var{file}:
>
> http://git.savannah.gnu.org/gitweb/?p=coreutils.git;a=commitdiff;h=1ce9d86c308d7daa6271a2e87629984b153ee9da

Thanks!
For a general policy-related change like that, I like
to add a rule so that "make check" enforces it, so I've made
the following change.  Note that it uncovered a few more.
It was a little tricky to automatically catch the cases in which
there were two @var{...} uses on a single line and the first one was ok.
There were two of those.

>From 016958f2f00fcdfb4a62099d0ef858dc9d4ac405 Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Mon, 1 Dec 2008 09:17:51 +0100
Subject: [PATCH] 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.
---
 doc/Makefile.am    |   33 +++++++++++++++++++-----
 doc/coreutils.texi |   70 ++++++++++++++++++++++++++--------------------------
 2 files changed, 61 insertions(+), 42 deletions(-)

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9d6997c..cba3332 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:address@hidden' $(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 =          \
+  '/address@hidden/ or next;           \
+   while (/address@hidden(.+?)}/g)     \
+     {                         \
+       $$v = $$1;              \
+       $$v =~ /[A-Z]/ && $$v !~ /^\\/ and (print "$$ARGV:$$.:$$_"), $$m = 1 \
+     }                         \
+   END {$$m and (warn "$(ME): do not use upper case in address@hidden"), 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 8dc8189..e331168 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -2024,13 +2024,13 @@ base64 invocation

 @table @samp

address@hidden -w @var{COLS}
address@hidden address@hidden
address@hidden -w @var{cols}
address@hidden address@hidden
 @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 @@ pr invocation
 Use a form feed instead of newlines to separate output pages.  This does
 not alter the default page length of 66 lines.

address@hidden -h @var{HEADER}
address@hidden address@hidden
address@hidden -h @var{header}
address@hidden address@hidden
 @opindex -h
 @opindex --header
 Replace the file name in the header with the centered string @var{header}.
@@ -2424,11 +2424,11 @@ pr invocation
 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 @@ wc invocation
 @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 @@ shuf invocation
 @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.,
address@hidden factorial, or @var{N} * (@var{N} - 1) * @dots{} * 1) possible
+general, if there are @var{n} input lines, there are @var{n}! (i.e.,
address@hidden factorial, or @var{n} * (@var{n} - 1) * @dots{} * 1) possible
 output permutations.

 @exitstatus
@@ -6270,7 +6270,7 @@ What information is listed
 @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 @@ shred invocation
 @cindex force deletion
 Override file permissions if necessary to allow overwriting.

address@hidden address@hidden
address@hidden -n @var{NUMBER}
address@hidden address@hidden
address@hidden -n @var{NUMBER}
address@hidden address@hidden
address@hidden address@hidden
address@hidden -n @var{number}
address@hidden address@hidden
address@hidden -n @var{number}
address@hidden address@hidden
 @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 @@ shred invocation
 Use @var{file} as a source of random data used to overwrite and to
 choose pass ordering.  @xref{Random sources}.

address@hidden -s @var{BYTES}
address@hidden address@hidden
address@hidden -s @var{BYTES}
address@hidden address@hidden
address@hidden -s @var{bytes}
address@hidden address@hidden
address@hidden -s @var{bytes}
address@hidden address@hidden
 @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 @@ touch invocation
 For example, @samp{-r foo -d '-5 seconds'} specifies a time stamp
 equal to five seconds before the corresponding time stamp for @file{foo}.

address@hidden -t address@hidden@address@hidden@var{ss}]
address@hidden -t address@hidden@address@hidden@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 @@ touch invocation
 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 @address@hidden@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 @address@hidden@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 @@ du invocation
 For each symbolic links encountered by @command{du},
 consider the disk space used by the symbolic link.

address@hidden address@hidden
address@hidden address@hidden
address@hidden address@hidden
address@hidden address@hidden
 @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 @@ du invocation
 Skip directories that are on different file systems from the one that
 the argument being processed is on.

address@hidden address@hidden
address@hidden address@hidden
address@hidden address@hidden
address@hidden address@hidden
 @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 @@ kill invocation
 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
 address@hidden address@hidden  The following commands are equivalent:
--
1.6.0.4.1101.g642f8