From d46cd1bca47e94e62ef558973a69761a729f298e Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sun, 2 Nov 2008 20:48:17 +0100
Subject: [PATCH] Add man page, README, INSTALL, generate index.html.

Change the layout of the help text so that both the man page and
the index.html look nice.
---
 INSTALL       |  14 ++++++
 Makefile      |  15 ++++++
 README        |  10 ++++
 adu.1.inc     |   4 ++
 adu.c         |  15 +++---
 adu.css       |  13 ++++++
 adu.ggo       |  14 +++---
 index.html.in | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++
 interactive.c |   4 +-
 select.ggo    |  84 +++++++++++++++++++--------------
 10 files changed, 250 insertions(+), 48 deletions(-)
 create mode 100644 INSTALL
 create mode 100644 README
 create mode 100644 adu.1.inc
 create mode 100644 adu.css
 create mode 100644 index.html.in

diff --git a/INSTALL b/INSTALL
new file mode 100644
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.
diff --git a/Makefile b/Makefile
index 187dd88..751506b 100644
--- 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
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
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
--- 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
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
--- 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
index 0000000..fdef4c0
--- /dev/null
+++ b/index.html.in
@@ -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>
+
diff --git a/interactive.c b/interactive.c
index 62ff5ed..288e9f3 100644
--- a/interactive.c
+++ b/interactive.c
@@ -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)
diff --git a/select.ggo b/select.ggo
index 78d6d75..a93007a 100644
--- a/select.ggo
+++ b/select.ggo
@@ -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.
 "
-- 
2.39.2