Add man page, README, INSTALL, generate index.html.
authorAndre Noll <maan@systemlinux.org>
Sun, 2 Nov 2008 19:48:17 +0000 (20:48 +0100)
committerAndre Noll <maan@systemlinux.org>
Sun, 2 Nov 2008 19:48:17 +0000 (20:48 +0100)
Change the layout of the help text so that both the man page and
the index.html look nice.

INSTALL [new file with mode: 0644]
Makefile
README [new file with mode: 0644]
adu.1.inc [new file with mode: 0644]
adu.c
adu.css [new file with mode: 0644]
adu.ggo
index.html.in [new file with mode: 0644]
interactive.c
select.ggo

diff --git a/INSTALL b/INSTALL
new file mode 100644 (file)
index 0000000..7956c35
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,14 @@
+As adu is based on libosl, the object storage layer, you first have
+to install libosl.
+
+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.
+
+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.
+
+The fancy logo was generated using skencil.
index 187dd88..751506b 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -52,5 +52,20 @@ select.cmdline.c select.cmdline.h: select.ggo
 select.cmdline.o: select.cmdline.c select.cmdline.h
        $(CC) -c $(CPPFLAGS) $<
 
+adu.1: adu adu.1.inc
+       help2man -h --detailed-help --include adu.1.inc -N ./$< > $@
+
+%.1.html: %.1
+       man2html $< | sed -e 's|^<DT><DD>$$|<DT><DD><br>|g' > $@
+
 clean:
        rm -f *.o adu *cmdline.c *cmdline.h
+
+index.html: adu.1.html index.html.in INSTALL README
+       sed -e '/@README@/,$$d' index.html.in > $@
+       grutatxt -nb < README >> $@
+       sed -e '1,/@README@/d' -e '/@INSTALL@/,$$d' index.html.in >> $@
+       grutatxt -nb < 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 >> $@
diff --git a/README b/README
new file mode 100644 (file)
index 0000000..5648ac5
--- /dev/null
+++ b/README
@@ -0,0 +1,10 @@
+adu creates a database containing disk usage statistics of a given
+directory. It allows to query that database to quickly retrieve usage
+patterns of subdirectories and/or files owned by a given user.
+
+Four different output modes are available: global list, global summary,
+user list, user summary. The format of the output may be customized
+via format strings.
+
+There's an interactive mode which allows to quickly launch many queries
+on the same database using different modes and different output files.
diff --git a/adu.1.inc b/adu.1.inc
new file mode 100644 (file)
index 0000000..9faf62d
--- /dev/null
+++ b/adu.1.inc
@@ -0,0 +1,4 @@
+[NAME]
+adu \- advanced disk usage
+[SEE ALSO]
+.BR du (1)
diff --git a/adu.c b/adu.c
index 8ce7317..335cb62 100644 (file)
--- a/adu.c
+++ b/adu.c
@@ -473,25 +473,26 @@ static int print_complete_help_and_die(void)
        const char **line;
        select_cmdline_parser_init(&select_conf);
 
+       printf("%s-%s\n", CMDLINE_PARSER_PACKAGE, CMDLINE_PARSER_VERSION);
+       printf("%s\n\n", gengetopt_args_info_purpose);
+       printf("%s\n\n", gengetopt_args_info_usage);
+
        if (conf.help_given)
                line = gengetopt_args_info_help;
        else
                line = gengetopt_args_info_detailed_help;
-
-       printf("adu command line options:\n");
-       printf("=========================\n");
        for (; *line; line++)
                printf("%s\n", *line);
+
        if (conf.help_given)
                line = select_args_info_help;
        else
                line  = select_args_info_detailed_help;
-       printf("select options:\n");
-       printf("===============\n");
+       printf("Select options:\n");
        for (; *line; line++)
                printf("%s\n", *line);
-       printf("interactive commands:\n");
-       printf("=====================\n");
+
+       printf("Interactive commands:\n");
        print_interactive_help();
        exit(EXIT_FAILURE);
 }
diff --git a/adu.css b/adu.css
new file mode 100644 (file)
index 0000000..2e66695
--- /dev/null
+++ b/adu.css
@@ -0,0 +1,13 @@
+BODY,TD {
+       background-color: #000000;
+       color: #CCCCCC;
+}
+
+HR {
+       background-color: #ffff00;
+}
+
+A {
+       color: #8888ff;
+
+}
diff --git a/adu.ggo b/adu.ggo
index 4c9b4fe..8c23e36 100644 (file)
--- a/adu.ggo
+++ b/adu.ggo
@@ -3,7 +3,7 @@
 # Licensed under the GPL v2. For licencing details see COPYING.
 
 package "adu"
-purpose "advanced disk usage
+purpose "
 
 adu creates a database containing disk usage statistics of a given
 directory. It allows to query that database to quickly retrieve
@@ -24,7 +24,6 @@ details="
        configuration file. As usual, if an option is given both at
        the command line and in the configuration file, the command
        line option takes precedence.
-
 "
 
 option "database-dir" d
@@ -95,6 +94,9 @@ details="
        In this mode, adu reads commands from stdin.  This makes it
        possible to run different select queries without opening the
        underlying osl database for each query (which is expensive).
+
+       In interactive mode, several subcommands are available, see
+       the end of this document.
 "
 
 groupoption "select" S
@@ -131,7 +133,7 @@ option "one-file-system" x
 flag off
 dependon="create"
 details="
-       Skip directories that are on different filesystems from the
+       Skip directories that are on different file systems from the
        one that the argument being processed is on.
 "
 
@@ -162,7 +164,7 @@ dependon="select"
 details="
        This option takes a string whose content is another set of
        options as described below.  Select options may be specified
-       either directly in select mode, in which case you have to quote
-       them to prevent them from being interpreted as adu options,
-       or via the \"set\" command in interactive mode.
+       either directly in select mode, in which case you have use
+       quotes to prevent the select options from being interpreted
+       as adu options, or via the \"set\" command in interactive mode.
 "
diff --git a/index.html.in b/index.html.in
new file mode 100644 (file)
index 0000000..fdef4c0
--- /dev/null
@@ -0,0 +1,125 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+   "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+       <meta http-equiv='Content-Type' content='text/html; charset=iso-8859-1'>
+       <title>ADU - Advanced disk usage</title>
+       <LINK href="adu.css" REL="stylesheet" TYPE="text/css">
+       <link rel="shortcut icon" href="adu.ico">
+</head>
+
+<body>
+       <table>
+               <tr>
+                       <td>
+                               <IMG SRC="adu.png" alt="adu">
+                       </td>
+                       <td>
+                               <h1>Advanced disk usage</h1>
+                       </td>
+               </tr>
+       </table>
+
+       <hr>
+
+       [<a href="#readme">README</a>]
+       [<a href="#download">Download</a>]
+       [<a href="#install">INSTALL</a>]
+       [<a href="#license">License</a>]
+       [<a href="#contact">Contact</a>]
+       [<a href="#manpage">Man page</a>]
+
+       <hr>
+
+       <center>
+               <h2>
+                       <a name="readme">README</a>
+               </h2>
+       </center>
+
+       @README@
+
+       <hr>
+
+
+       <center>
+               <h2>
+                       <a name="download">Download</a>
+               </h2>
+       </center>
+
+       <p>Only the source code is available for download. Use
+
+               <a href="http://www.kernel.org/pub/software/scm/git/docs/">git</a>
+
+       to clone the adu repository by executing</p>
+
+       <center>
+
+               <tt>git clone git://git.tuebingen.mpg.de/adu</tt>
+
+       </center>
+
+       <p> or grab the
+
+       <a href="http://git.tuebingen.mpg.de/cgi-bin/gitweb.cgi?p=adu.git;a=snapshot;h=HEAD;sf=tgz">tarball</a>
+
+       of the current tree. If you prefer to download the tarball of
+       the latest release, select the corresponding <em>snapshot</em>
+       link on the
+
+               <a href="http://git.tuebingen.mpg.de/adu">adu gitweb page</a>
+
+       </p>
+
+       <hr>
+
+       <center>
+               <h2>
+                       <a name="install">INSTALL</a>
+               </h2>
+       </center>
+
+       @INSTALL@
+
+       <hr>
+
+       <center>
+               <h2>
+                       <a name="license">License</a>
+               </h2>
+       </center>
+
+       <p>adu is open source software, licensed under the
+
+       <a
+       href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU
+       General Public License, Version 2</a>.</p>
+
+       <hr>
+
+       <center>
+               <h2>
+                       <a name="contact">Contact</a>
+               </h2>
+       </center>
+
+       <p> Andr&eacute; Noll, <a
+       href="mailto:maan@systemlinux.org">maan@systemlinux.org</a>
+       </p> Comments and bug reports are welcome. Please provide
+       enough info such as the version of adu/libosl you are using
+       and relevant parts of the logs. Including the string [adu]
+       in the subject line is also a good idea.
+
+       <hr>
+
+       <center>
+               <h2>
+                       <a name="manpage">Man page</a>
+               </h2>
+       </center>
+
+       @MAN_PAGE@
+
+</body> </html>
+
index 62ff5ed..288e9f3 100644 (file)
@@ -65,7 +65,9 @@ static int icom_help(__a_unused char *line)
 
 void print_interactive_help(void)
 {
-       icom_help(NULL);
+       struct interactive_command *c;
+       FOR_EACH_COMMAND(c)
+               fprintf(stdout, "\t%s\t%s\n", c->name, c->desc);
 }
 
 static int icom_reset(__a_unused char *line)
index 78d6d75..a93007a 100644 (file)
@@ -8,10 +8,17 @@ details="
        An uid specifier may be a single number, or a range of uids.
        Example:
 
-       --uid 42    # only consider uid 42
-       --uid 42-   # only consider uids greater or equal than 42
-       --uid 23-42 # only consider uids between 23 and 42, inclusively.
-       --uid 23-42,666-777,88 # consider uids 23-42, 666-777 and 88.
+       Only consider uid 42:
+               --uid 42
+
+       Only consider uids greater or equal than 42:
+               --uid 42-
+
+       Only consider uids between 23 and 42, inclusively:
+               --uid 23-42
+
+       Consider uids 23-42, 666-777 and 88:
+               --uid 23-42,666-777,88
 "
 
 option "limit" L
@@ -27,7 +34,7 @@ details="
 
 option "no-headers" -
 #~~~~~~~~~~~~~~~~~~~~
-"supress descriptions for listings/summaries"
+"suppress descriptions for listings/summaries"
 flag off
 details="
        This is mostly useful to feed the output of adu to scripts.
@@ -97,8 +104,9 @@ option "format" f
 string typestr="<format_string>"
 optional
 details="
+
        A string that specifies how the output of the select query is
-       goint to be formated.  Depending on the chosen select-mode,
+       going to be formated.  Depending on the chosen select-mode,
        several conversion specifiers are available and a different
        default value for this option applies.
 
@@ -116,14 +124,18 @@ details="
        positive integer.  Both \"a\" and \"w\" are optional.
 
        A string directive supported by adu is \"dirname\" which is
-       subsitituted by the name of the directory. It is available
+       substituted by the name of the directory. It is available
        if either user_list or global_list mode was selected via
        --select-mode.
 
        Examples:
+               Print dirname without any padding:
 
-               \"%(diname)\" # print dirname without any padding
-               \"%(dirname:c:20)\" # center dirname in a 20 chars wide field
+               \"%(diname)\"
+
+               Center dirname in a 20 chars wide field:
+
+               \"%(dirname:c:20)\"
 
        The other two types of directives, count and size, are used
        for numbers. The syntax for these is %(name:a:w:u). The \"a\"
@@ -155,30 +167,34 @@ details="
        tab character for these combinations respectively.
 
        Examples:
+               Print size in gigabytes right-aligned:
+                       \"%(size:r::G)\"
+
+               As before, but use 5 char wide field:
+                       \"%(size:r5::G)\"
+
+               As before, but suppress trailing \"G\":
+                       \"%(size:r5::*G)\"
+
+
+       The following list contains all directives known to adu,
+       together with their types, and for which modes each of
+       them may be used.
+
+               pw_name (string): user name. Available for user_list
+               and user_summary
+
+               uid (id): user id. Available for user_list and
+               user_summary.
+
+               files (count): number of files. Available everywhere.
+
+               dirname (string): name of the directory. Available
+               for user_list and global_list.
+
+               size (size): total size/ directory size. Available
+               everywhere.
 
-               \"%(size:r::G)\" # print size in gigabytes right-aligned
-               \"%(size:r5::G)\" # as before, but use 5 char wide field
-               \"%(size:r5::*G)\" # as before, but supress trailing \"G\"
-
-       List of directives and types known to adu, together with their types:
-
-               name            type            meaning
-               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-               pw_name         string          user name
-               uid             id              user id
-               files           count           number of files
-               dirname         string          name of the directory
-               size            size            total size/ directory size
-               dirs            count           number of directories
-
-       Not all directives are available for each mode:
-
-               name            available in directives
-               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-               pw_name         user_list, user_summary
-               uid             user_list, user_summary
-               files           everywhere
-               dirname         user_list, global_list
-               size            everywhere
-               dirs            suer_summary, global_summary
+               dirs (count): number of directories. Available
+               for user_summary and global_summary.
 "