Pádraig Brady <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]>
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:[EMAIL PROTECTED]' $(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 = \
+ '/[EMAIL PROTECTED]/ or next; \
+ while (/[EMAIL PROTECTED](.+?)}/g) \
+ { \
+ $$v = $$1; \
+ $$v =~ /[A-Z]/ && $$v !~ /^\\/ and (print "$$ARGV:$$.:$$_"), $$m = 1 \
+ } \
+ END {$$m and (warn "$(ME): do not use upper case in [EMAIL PROTECTED]"),
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
[EMAIL PROTECTED] -w @var{COLS}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -w @var{cols}
[EMAIL PROTECTED] [EMAIL PROTECTED]
@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.
[EMAIL PROTECTED] -h @var{HEADER}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -h @var{header}
[EMAIL PROTECTED] [EMAIL PROTECTED]
@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.,
[EMAIL PROTECTED] factorial, or @var{N} * (@var{N} - 1) * @dots{} * 1) possible
+general, if there are @var{n} input lines, there are @var{n}! (i.e.,
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -n @var{NUMBER}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -n @var{NUMBER}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -n @var{number}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -n @var{number}
[EMAIL PROTECTED] [EMAIL PROTECTED]
@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}.
[EMAIL PROTECTED] -s @var{BYTES}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -s @var{BYTES}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -s @var{bytes}
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] -s @var{bytes}
[EMAIL PROTECTED] [EMAIL PROTECTED]
@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}.
[EMAIL PROTECTED] -t [EMAIL PROTECTED]@[EMAIL PROTECTED]@var{ss}]
[EMAIL PROTECTED] -t [EMAIL PROTECTED]@[EMAIL PROTECTED]@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 @[EMAIL PROTECTED]@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 @[EMAIL PROTECTED]@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.
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
@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.
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
@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
[EMAIL PROTECTED] [EMAIL PROTECTED] The following commands are equivalent:
--
1.6.0.4.1101.g642f8
_______________________________________________
Bug-coreutils mailing list
Bug-coreutils@gnu.org
http://lists.gnu.org/mailman/listinfo/bug-coreutils
