summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJim Meyering <meyering@redhat.com>2008-12-01 09:17:51 +0100
committerJim Meyering <meyering@redhat.com>2008-12-01 09:25:06 +0100
commit016958f2f00fcdfb4a62099d0ef858dc9d4ac405 (patch)
tree45a906915ace67776cca95f0937cc99b58d72083
parent1ce9d86c308d7daa6271a2e87629984b153ee9da (diff)
downloadcoreutils-016958f2f00fcdfb4a62099d0ef858dc9d4ac405.tar.xz
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.
-rw-r--r--doc/Makefile.am33
-rw-r--r--doc/coreutils.texi70
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: