coreutils
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH] doc: use consistent example format in manual


From: Pádraig Brady
Subject: [PATCH] doc: use consistent example format in manual
Date: Sat, 20 Jan 2018 20:34:34 -0800

* doc/coreutils.texi: Use @example consistently
as we don't need the smaller or fixed width representation.
This is especially true for the synposis of commands.
@smallexample is rendered left aligned for HTML
which is awkward to read with the center aligned main content.
---
 doc/coreutils.texi | 124 ++++++++++++++++++++++++++---------------------------
 1 file changed, 62 insertions(+), 62 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 9f5f95b..cdde136 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -1336,9 +1336,9 @@ The @option{--target-directory} (@option{-t}) option 
allows the @command{cp},
 conveniently with @command{xargs}.  For example, you can move the files
 from the current directory to a sibling directory, @code{d} like this:
 
address@hidden
address@hidden
 ls | xargs mv -t ../d --
address@hidden smallexample
address@hidden example
 
 However, this doesn't move files whose names begin with @samp{.}.
 If you use the GNU @command{find} program, you can move those
@@ -1679,13 +1679,13 @@ if standard output is a terminal.
 
 Examples:
 
address@hidden
address@hidden
 # Output f's contents, then standard input, then g's contents.
 cat f - g
 
 # Copy standard input to standard output.
 cat
address@hidden smallexample
address@hidden example
 
 
 @node tac invocation
@@ -1922,12 +1922,12 @@ Use @var{number} characters for line numbers (default 
6).
 (@samp{-} means standard input), or standard input if none are given.
 Synopses:
 
address@hidden
address@hidden
 od address@hidden@dots{} address@hidden@dots{}
 od address@hidden address@hidden address@hidden
 od address@hidden@dots{} --traditional address@hidden@c
  address@hidden address@hidden
address@hidden smallexample
address@hidden example
 
 Each line of output consists of the offset in the input, followed by
 groups of data from the file.  By default, @command{od} prints the offset in
@@ -2158,9 +2158,9 @@ Output as hexadecimal two-byte units.  Equivalent to 
@samp{-t x2}.
 Recognize the non-option label argument that traditional @command{od}
 accepted.  The following syntax:
 
address@hidden
address@hidden
 od --traditional address@hidden address@hidden address@hidden
address@hidden smallexample
address@hidden example
 
 @noindent
 can be used to specify at most one file and optional arguments
@@ -2199,10 +2199,10 @@ into (or from) base64 encoded form.  The base64 encoded 
form uses
 printable ASCII characters to represent binary data.
 Synopses:
 
address@hidden
address@hidden
 base64 address@hidden@dots{} address@hidden
 base64 --decode address@hidden@dots{} address@hidden
address@hidden smallexample
address@hidden example
 
 The base64 encoding expands data to roughly 133% of the original.
 The base32 encoding expands data to roughly 160% of the original.
@@ -4729,9 +4729,9 @@ sorts is stable.
 @item
 Generate a tags file in case-insensitive sorted order.
 
address@hidden
address@hidden
 find src -type f -print0 | sort -z -f | xargs -0 etags --append
address@hidden smallexample
address@hidden example
 
 The use of @option{-print0}, @option{-z}, and @option{-0} in this case means
 that file names that contain blanks or other special characters are
@@ -5593,10 +5593,10 @@ generating output suitable for @command{nroff}, 
@command{troff} or @TeX{}.
 Choose an output format suitable for @command{nroff} or @command{troff}
 processing.  Each output line will look like:
 
address@hidden
address@hidden
 .xx "@var{tail}" "@var{before}" "@var{keyword_and_after}"@c
  "@var{head}" "@var{ref}"
address@hidden smallexample
address@hidden example
 
 so it will be possible to write a @samp{.xx} roff macro to take care of
 the output typesetting.  This is the default output format when GNU
@@ -5616,10 +5616,10 @@ so it will be correctly processed by @command{nroff} or 
@command{troff}.
 Choose an output format suitable for @TeX{} processing.  Each output
 line will look like:
 
address@hidden
address@hidden
 \xx @address@hidden@address@hidden@address@hidden@address@hidden@address@hidden
 @address@hidden@address@hidden@address@hidden@address@hidden@}
address@hidden smallexample
address@hidden example
 
 @noindent
 so it will be possible to write a @code{\xx} definition to take care of
@@ -7332,9 +7332,9 @@ in the shell, an initial @samp{.} in a file name does not 
match a
 wildcard at the start of @var{pattern}.  Sometimes it is useful
 to give this option several times.  For example,
 
address@hidden
address@hidden
 $ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
address@hidden smallexample
address@hidden example
 
 The first option ignores names of length 3 or more that start with @samp{.},
 the second ignores all two-character names that start with @samp{.}
@@ -8640,11 +8640,11 @@ Then the @option{--preserve=links} option also implied 
by @option{-a}
 will preserve the perceived hard link.
 
 Here is a similar example that exercises @command{cp}'s @option{-L} option:
address@hidden
address@hidden
 $ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b
 74163295 a
 74163295 b
address@hidden smallexample
address@hidden example
 
 @item context
 Preserve SELinux security context of the file, or fail with full diagnostics.
@@ -10382,10 +10382,10 @@ Make symbolic links relative to the link location.
 
 Example:
 
address@hidden
address@hidden
 ln -srv /a/file /tmp
 '/tmp/file' -> '../a/file'
address@hidden smallexample
address@hidden example
 
 Relative symbolic links are generated based on their canonicalized
 containing directory, and canonicalized targets.  I.e., all symbolic
@@ -10440,7 +10440,7 @@ if @code{link} follows symbolic links (such as on BSD).
 
 Examples:
 
address@hidden
address@hidden
 Bad Example:
 
 # Create link ../a pointing to a in that directory.
@@ -10464,7 +10464,7 @@ Better Example:
 # work across networked file systems.
 ln -s afile anotherfile
 ln -s ../adir/afile yetanotherfile
address@hidden smallexample
address@hidden example
 
 
 @node mkdir invocation
@@ -10980,9 +10980,9 @@ it narrows considerably the window of potential abuse.
 For example, to reflect a user ID numbering change for one user's files
 without an option like this, @code{root} might run
 
address@hidden
address@hidden
 find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER
address@hidden smallexample
address@hidden example
 
 But that is dangerous because the interval between when the @command{find}
 tests the existing file's owner and when the @command{chown} is actually run
@@ -11077,7 +11077,7 @@ Recursively change ownership of directories and their 
contents.
 
 Examples:
 
address@hidden
address@hidden
 # Change the owner of /u to "root".
 chown root /u
 
@@ -11086,7 +11086,7 @@ chown root:staff /u
 
 # Change the owner of /u and subfiles to "root".
 chown -hR root /u
address@hidden smallexample
address@hidden example
 
 
 @node chgrp invocation
@@ -11208,13 +11208,13 @@ Recursively change the group ownership of directories 
and their contents.
 
 Examples:
 
address@hidden
address@hidden
 # Change the group of /u to "staff".
 chgrp staff /u
 
 # Change the group of /u and subfiles to "staff".
 chgrp -hR staff /u
address@hidden smallexample
address@hidden example
 
 
 @node chmod invocation
@@ -12736,13 +12736,13 @@ use GNU recode 3.5c (or newer) to convert strings to 
this encoding.  Here
 is how to convert a piece of text into a shell script which will output
 this text in a locale-independent way:
 
address@hidden
address@hidden
 $ LC_CTYPE=zh_CN.big5 /usr/local/bin/printf \
     '\u4e2d\u6587\n' > sample.txt
 $ recode BIG5..JAVA < sample.txt \
     | sed -e "s|^|/usr/local/bin/printf '|" -e "s|$|\\\\n'|" \
     > sample.sh
address@hidden smallexample
address@hidden example
 
 @exitstatus
 
@@ -13777,7 +13777,7 @@ This option implies the @option{-a} option.
 
 Examples:
 
address@hidden
address@hidden
 # Output "sort".
 basename /usr/bin/sort
 
@@ -13789,7 +13789,7 @@ basename -s .h include/stdio.h
 
 # Output "stdio" followed by "stdlib"
 basename -a -s .h include/stdio.h include/stdlib.h
address@hidden smallexample
address@hidden example
 
 
 @node dirname invocation
@@ -13832,7 +13832,7 @@ The program accepts the following option.  Also see 
@ref{Common options}.
 
 Examples:
 
address@hidden
address@hidden
 # Output "/usr/bin".
 dirname /usr/bin/sort
 dirname /usr/bin//.//
@@ -13842,7 +13842,7 @@ dirname dir1/str dir2/str
 
 # Output ".".
 dirname stdio.h
address@hidden smallexample
address@hidden example
 
 
 @node pathchk invocation
@@ -16209,26 +16209,26 @@ date -u --date=2000-01-01 +%s
 To convert such an unwieldy number of seconds back to
 a more readable form, use a command like this:
 
address@hidden
address@hidden
 # local time zone used
 date -d '1970-01-01 UTC 946684800 seconds' +"%Y-%m-%d %T %z"
 1999-12-31 19:00:00 -0500
address@hidden smallexample
address@hidden example
 
 Or if you do not mind depending on the @samp{@@} feature present since
 coreutils 5.3.0, you could shorten this to:
 
address@hidden
address@hidden
 date -d @@946684800 +"%F %T %z"
 1999-12-31 19:00:00 -0500
address@hidden smallexample
address@hidden example
 
 Often it is better to output UTC-relative date and time:
 
address@hidden
address@hidden
 date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d %T %z"
 2000-01-01 00:00:00 +0000
address@hidden smallexample
address@hidden example
 
 @item
 @cindex leap seconds
@@ -16352,11 +16352,11 @@ The information may contain internal spaces, so such 
output cannot be
 parsed reliably.  In the following example, @var{release} is
 @samp{2.2.18ss.e820-bda652a #4 SMP Tue Jun 5 11:24:08 PDT 2001}:
 
address@hidden
address@hidden
 uname -a
 @result{} Linux dumdum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 address@hidden
  unknown unknown GNU/Linux
address@hidden smallexample
address@hidden example
 
 
 The program accepts the following options.  Also see @ref{Common options}.
@@ -16574,12 +16574,12 @@ contexts.
 @command{chcon} changes the SELinux security context of the selected files.
 Synopses:
 
address@hidden
address@hidden
 chcon address@hidden@dots{} @var{context} @address@hidden
 chcon address@hidden@dots{} [-u @var{user}] [-r @var{role}] [-l @address@hidden
  [-t @var{type}] @address@hidden
 chcon address@hidden@dots{} address@hidden @address@hidden
address@hidden smallexample
address@hidden example
 
 Change the SELinux security context of each @var{file} to @var{context}.
 With @option{--reference}, change the security context of each @var{file}
@@ -16677,11 +16677,11 @@ Set range @var{range} in the target security context.
 @command{runcon} runs file in specified SELinux security context.
 
 Synopses:
address@hidden
address@hidden
 runcon @var{context} @var{command} address@hidden
 runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @address@hidden
  [-l @var{range}] @var{command} address@hidden
address@hidden smallexample
address@hidden example
 
 Run @var{command} with completely-specified @var{context}, or with
 current or transitioned security context modified by one or more of 
@var{level},
@@ -18308,9 +18308,9 @@ water pipeline.
 
 With the Unix shell, it's very easy to set up data pipelines:
 
address@hidden
address@hidden
 program_to_create_data | filter1 | ... | filterN > final.pretty.data
address@hidden smallexample
address@hidden example
 
 We start out by creating the raw data; each filter applies some successive
 transformation to the data, until by the time it comes out of the pipeline,
@@ -18590,9 +18590,9 @@ The next step is to get rid of punctuation.  Quoted 
words and unquoted words
 should be treated identically; it's easiest to just get the punctuation out of
 the way.
 
address@hidden
address@hidden
 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ...
address@hidden smallexample
address@hidden example
 
 The second @command{tr} command operates on the complement of the listed
 characters, which are all the letters, the digits, the underscore, and
@@ -18605,10 +18605,10 @@ The words only contain alphanumeric characters (and 
the underscore).  The
 next step is break the data apart so that we have one word per line.  This
 makes the counting operation much easier, as we will see shortly.
 
address@hidden
address@hidden
 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
 > tr -s ' ' '\n' | ...
address@hidden smallexample
address@hidden example
 
 This command turns blanks into newlines.  The @option{-s} option squeezes
 multiple newline characters in the output into just one, removing
@@ -18619,10 +18619,10 @@ typing in all of a command.)
 We now have data consisting of one word per line, no punctuation, all one
 case.  We're ready to count each word:
 
address@hidden
address@hidden
 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
 > tr -s ' ' '\n' | sort | uniq -c | ...
address@hidden smallexample
address@hidden example
 
 At this point, the data might look something like this:
 
@@ -18651,7 +18651,7 @@ reverse the order of the sort
 
 The final pipeline looks like this:
 
address@hidden
address@hidden
 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
 > tr -s ' ' '\n' | sort | uniq -c | sort -n -r
 @print{}    156 the
@@ -18660,7 +18660,7 @@ $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd 
'[:alnum:]_ \n' |
 @print{}     51 of
 @print{}     51 and
 @dots{}
address@hidden smallexample
address@hidden example
 
 Whew!  That's a lot to digest.  Yet, the same principles apply.  With six
 commands, on two lines (really one long one split for convenience), we've
@@ -18679,19 +18679,19 @@ this is a sorted, 45,402 word dictionary.
 Now, how to compare our file with the dictionary?  As before, we generate
 a sorted list of words, one per line:
 
address@hidden
address@hidden
 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
 > tr -s ' ' '\n' | sort -u | ...
address@hidden smallexample
address@hidden example
 
 Now, all we need is a list of words that are @emph{not} in the
 dictionary.  Here is where the @command{comm} command comes in.
 
address@hidden
address@hidden
 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
 > tr -s ' ' '\n' | sort -u |
 > comm -23 - /usr/dict/words
address@hidden smallexample
address@hidden example
 
 The @option{-2} and @option{-3} options eliminate lines that are only in the
 dictionary (the second file), and lines that are in both files.  Lines
-- 
2.9.3




reply via email to

[Prev in Thread] Current Thread [Next in Thread]