Merge branch 'refs/heads/t/doc-improvements'
authorAndre Noll <maan@tuebingen.mpg.de>
Sun, 26 Mar 2017 16:04:52 +0000 (18:04 +0200)
committerAndre Noll <maan@tuebingen.mpg.de>
Sun, 26 Mar 2017 16:04:52 +0000 (18:04 +0200)
Another topic branch that was cooking for far too long.

* refs/heads/t/doc-improvements:
  Switch from grutatxt to markdown.
  INSTALL: Link to the gengetopt web page.
  manual: Fix a whitespace issue.
  manual: Add example for interactive mode.
  manual: Add two more examples.
  manual: Add example query for omitting a directory.
  manual: Add short option example.
  manual: Remove pointless "time" prefix.
  manual: Improve documentation of --output.

INSTALL
Makefile
adu.1.inc
select.ggo

diff --git a/INSTALL b/INSTALL
index 82c9f71..4bababb 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,12 +1,10 @@
 As adu is based on libosl, the object storage layer, you first have
-to install http://people.tuebingen.mpg.de/maan/osl/ (libosl).
+to install [libosl](http://people.tuebingen.mpg.de/maan/osl/).
 
-Adu's command line parser and the interactive help
-are generated using gnu gengetopt. You'll likely need a
-ftp://ftp.gnu.org/pub/gnu/gengetopt/ (recent version) to compile adu
-from source.
+Adu's command line parser and the interactive help are generated by
+[gnu gengetopt](http://www.gnu.org/software/gengetopt/gengetopt.html).
+Hence the gengetopt package must be installed to compile adu from
+source.
 
-In order to generate the man page,
-ftp://ftp.gnu.org/pub/gnu/help2man (help2man)
-must be installed. For the html version of the man page,
-http://www.triptico.com/software/grutatxt.html (grutatxt) is used.
+To generate the man page,
+[help2man](ftp://ftp.gnu.org/pub/gnu/help2man) must be installed.
index 58202a2..8e4d653 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -76,9 +76,9 @@ clean:
 
 index.html: adu.1.html index.html.in INSTALL README
        sed -e '/@README@/,$$d' index.html.in > $@
-       grutatxt -nb < README >> $@
+       markdown README >> $@
        sed -e '1,/@README@/d' -e '/@INSTALL@/,$$d' index.html.in >> $@
-       grutatxt -nb < INSTALL >> $@
+       markdown INSTALL >> $@
        sed -e '1,/@INSTALL@/d' -e '/@MAN_PAGE@/,$$d' index.html.in >> $@
        sed -e '1,/Return to Main Contents/d' -e '/Index/,$$d' adu.1.html >> $@
        sed -e '1,/@MAN_PAGE@/d' index.html.in >> $@
index b8be2e1..4cf6fcd 100644 (file)
--- a/adu.1.inc
+++ b/adu.1.inc
@@ -7,18 +7,50 @@ The following example creates a database containing the disk usage
 patterns of the /var directory:
 .IP
        $ adu --create --database-dir /root/adu-var --base-dir /var
-
 .PP
 Here's a simple query that uses the newly created database to print
 the user-summary:
 .IP
        $ adu --select --database-dir /root/adu-var
-
+.PP
+To print the one-line global summary instead, use
+.IP
+       $ adu --select --database-dir /root/adu-var --select-options '--select-mode global_summary'
+.PP
+To sort the user summary by file count rather than by file size, run
+.IP
+       $ adu --select --database-dir /root/adu-var --select-options '--list-sort=file_count'
 .PP
 The command below prints the five largest directories of the users root and
 mysql:
 .IP
-       $ time adu --select --database-dir /root/adu-var --select-options '--select-mode user_list --user root --user mysql --limit 5'
+       $ adu --select --database-dir /root/adu-var --select-options '--select-mode user_list --user root --user mysql --limit 5'
+.PP
+The same, using short options:
+.IP
+       $ adu -Sd /root/adu-var -s '-m user_list -u root -u mysql -l 5'
+.PP
+Again the same, but omitting /var/cache:
+.IP
+       $ adu -Sd /root/adu-var -s '-m user_list -u root -u mysql -l 5 -p !^cache/'
+.PP
+A simple script for interactive mode:
+
+.EX
+       set -m user_list
+       set -u root
+       set -o file-list.root
+       run
+       reset
+       set -m user_list
+       set -u mysql
+       set -o file-list.mysql
+       run
+.EE
+.PP
+Run adu in interactive mode with the above script (adu-script.txt):
+.IP
+       $ adu -Id /root/adu-var < adu-script.txt
 
 [SEE ALSO]
 .BR du (1)
index d966095..d7f8c93 100644 (file)
@@ -134,28 +134,32 @@ string typestr="path"
 optional
 default="-"
 details="
-       If empty, or not given, use stdout. The following conventions
-       cause the output to be written differently:
-
-       An output file name of \"-\" means stdout.
-
-       \"path\" may be prepended by '>' which instructs adu to
-       truncate the output file to length zero.  If \"path\" does
-       not start with '>' and \"path\" already exists, the select
-       query is being aborted. Otherwise, \"path\" is created and
-       output is written to \"path\".
-
-       If the first two characters of \"path\" are '>', the output
-       file (given by removing the leading \">>\" from \"path\")
-       is being opened in append mode. It is no error if the output
-       file does not exist but, as above, the output file name \">>\"
-       is considered invalid.
-
-       If the first character of \"path\" is '|', a pipe is created
-       and the rest of \"path\" is being executed with its standard in
-       redirected to the reading end of the pipe. The output of adu
-       is written to the writing end of the pipe. Again, specifying
-       only \"|\" is considered invalid and causes an error.
+       This option is only useful in interactive mode. If stdin is redirected
+       from a script, and the script contains several queries one can use
+       this option to let each query write its output to a different file.
+
+       If the option is not given, or its argument is either \"-\" or the
+       empty string, stdout is assumed. The following conventions cause the
+       output to be written in a different way:
+
+       \"path\" may be prepended by '>' which instructs adu to truncate
+       the output file to length zero. If \"path\" does not start with
+       '>' and \"path\" already exists, the query is aborted. Otherwise,
+       the file is created and truncated. The output file name \">\" is
+       considered invalid.
+
+       If the first two characters of \"path\" are '>', the output file
+       (given by removing the leading \">>\" from \"path\") is opened in
+       append mode. It is no error if the output file does not exist. However,
+       as above the output file name \">>\" is considered invalid.
+
+       If the first character of \"path\" is '|', a pipe is created and the
+       rest of \"path\" is executed with stdin redirected to the reading
+       end of the pipe while the query output is written to the writing end
+       of the pipe. Again, specifying only \"|\" is considered invalid and
+       causes an error.
+
+       See the manual page for examples.
 "
 
 option "user-summary-sort" -