- changed the way POD is generated such that the dashed

  line appears at the bottom instead of the top.  The
  indentation semantics of POD make the first item in
  the (=over,=back) block look weird the other way.
- implemented a way to encode example usage into usage.h
  One would define a macro called "${applet}_example_usage"
  which would expand to the example text.
- The example usage is considered optional, but trivial and
  full usage are not.

  Here's an example using chown.

---- before

#define chown_trivial_usage \
	"[OPTION]...  OWNER[<.|:>[GROUP] FILE..."
#define chown_full_usage \
	"Change the owner and/or group of each FILE to OWNER and/or GROUP.\n" \
	"\nOptions:\n" \
	"\t-R\tChanges files and directories recursively."
#define chown_example_usage \
	"\t$ ls -l /tmp/foo\n" \
	"\t-r--r--r--    1 andersen andersen        0 Apr 12 18:25 /tmp/foo\n" \
	"\t$ chown root /tmp/foo\n" \
	"\t$ ls -l /tmp/foo\n" \
	"\t-r--r--r--    1 root     andersen        0 Apr 12 18:25 /tmp/foo\n" \
	"\t$ chown root.root /tmp/foo\n" \
	"\tls -l /tmp/foo\n" \
	"\t-r--r--r--    1 root     root            0 Apr 12 18:25 /tmp/foo\n"

---- after

=item I<chown>

chown [OPTION]...  OWNER[<.|:>[GROUP] FILE...

Change the owner and/or group of each FILE to OWNER and/or GROUP.

Options:

	-R	Changes files and directories recursively.

Example:

	$ ls -l /tmp/foo
	-r--r--r--    1 andersen andersen        0 Apr 12 18:25 /tmp/foo
	$ chown root /tmp/foo
	$ ls -l /tmp/foo
	-r--r--r--    1 root     andersen        0 Apr 12 18:25 /tmp/foo
	$ chown root.root /tmp/foo
	ls -l /tmp/foo
	-r--r--r--    1 root     root            0 Apr 12 18:25 /tmp/foo

-------------------------------

diff --git a/docs/autodocifier.pl b/docs/autodocifier.pl
index 6822db51e4be442ef1cfd8e12bd81e8329eb21f5..2d5e04a2ed03153c30c86aa1f77c37f7dabc1d1f 100755 (executable)
--- a/docs/autodocifier.pl
+++ b/docs/autodocifier.pl
@@ -30,6 +30,7 @@ sub beautify {
                        s/^\s*//;
                        s/"//g;
                        s/%/%%/g;
+                       s/\$/\\\$/g;
                        eval qq[ sprintf(qq#$_#) ]
                } @line
        );
@@ -43,7 +44,7 @@ sub pod_for_usage {
 
        # make options bold
        my $trivial = $usage->{trivial};
-       $trivial =~s/(?<!\w)(-\w+)/B<$1>/sxg;
+       $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg;
        my @f0 = 
                map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ }
                split("\n", $usage->{full});
@@ -59,16 +60,22 @@ sub pod_for_usage {
                        push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s);
                }
        }
-
        my $full = join("\n", @f1);
+
+       # prepare example if one exists
+       my $example = (defined $usage->{example})
+               ? "Example:\n\n$usage->{example}\n\n"
+               : "";
+
        return
-               "-------------------------------\n".
-               "\n".
-               "=item $name".
-               "\n\n".
+               "=item I<$name>".
+               "\n\n"  .
                "$name $trivial".
-               "\n\n".
-               $full.
+               "\n\n"  .
+               $full   .
+               "\n\n"  .
+               $example.
+               "-------------------------------".
                "\n\n"
        ;
 }
@@ -121,7 +128,7 @@ if (defined $opt{help}) {
 # collect documenation into %docs
 
 foreach (@ARGV) {
-       open(USAGE, $_) || die("$0: $!");
+       open(USAGE, $_) || die("$0: $_: $!");
        my $fh = *USAGE;
        my ($applet, $type, @line);
        while (<$fh>) {
@@ -209,4 +216,4 @@ John BEPPU <beppu@lineo.com>
 
 =cut
 
-# $Id: autodocifier.pl,v 1.12 2001/02/24 14:44:25 beppu Exp $
+# $Id: autodocifier.pl,v 1.13 2001/02/26 02:50:11 beppu Exp $