From d11578f9167a5bc10cf77544cc1d64965d3f8f2b Mon Sep 17 00:00:00 2001 From: John Beppu Date: Mon, 26 Feb 2001 02:50:11 +0000 Subject: - 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 [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 ------------------------------- --- docs/autodocifier.pl | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/autodocifier.pl b/docs/autodocifier.pl index 6822db5..2d5e04a 100755 --- 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/(?/sxg; + $trivial =~ s/(?/sxg; my @f0 = map { $_ !~ /^\s/ && s/(?/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 =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 $ -- cgit v1.1