X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=docs%2Fautodocifier.pl;h=377c8b55b385c524128730d7667b16f9974ee346;hb=88947dd05e28a3b793b16dfd6db1b5414ca99017;hp=67e43b2d5f988168b214ceb3e58aa364481c26ae;hpb=dbfff6cbde0231e4904be1be97ee699ca4cae682;p=oweals%2Fbusybox.git diff --git a/docs/autodocifier.pl b/docs/autodocifier.pl index 67e43b2d5..377c8b55b 100755 --- a/docs/autodocifier.pl +++ b/docs/autodocifier.pl @@ -11,7 +11,7 @@ sub continuation { while (<$fh>) { my $s = $_; $s =~ s/\\\s*$//; - $s =~ s/#.*$//; + #$s =~ s/#.*$//; push @line, $s; last unless (/\\\s*$/); } @@ -26,15 +26,13 @@ sub beautify { $text =~ s/"\s*"//sg; my @line = split("\n", $text); $text = join('', - map { eval } - map { qq[ sprintf(qq#$_#) ] } map { - s/^\s*//; - s/"//g; - s/% /%% /g; - $_ - } - @line + s/^\s*"//; + s/"\s*$//; + s/%/%%/g; + s/\$/\\\$/g; + eval qq[ sprintf(qq{$_}) ] + } @line ); return $text; } @@ -46,14 +44,14 @@ sub pod_for_usage { # make options bold my $trivial = $usage->{trivial}; - $trivial =~s/(?/sxg; - my @f1; + $trivial =~ s/(?/sxg; my @f0 = map { $_ !~ /^\s/ && s/(?/g; $_ } split("\n", $usage->{full}); # add "\n" prior to certain lines to make indented # lines look right + my @f1; my $len = @f0; for (my $i = 0; $i < $len; $i++) { push @f1, $f0[$i]; @@ -62,21 +60,37 @@ sub pod_for_usage { push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s); } } - my $full = join("\n", @f1); + + # prepare notes if they exist + my $notes = (defined $usage->{notes}) + ? "$usage->{notes}\n\n" + : ""; + + # prepare examples if they exist + my $example = (defined $usage->{example}) + ? + "Example:\n\n" . + join ("\n", + map { "\t$_" } + split("\n", $usage->{example})) . "\n\n" + : ""; + return - "-------------------------------\n". - "\n". - "=item $name". - "\n\n". + "=item B<$name>". + "\n\n" . "$name $trivial". - "\n\n". - $full. + "\n\n" . + $full . + "\n\n" . + $notes . + $example. + "-------------------------------". "\n\n" ; } -# generate SGML for an applet +# FIXME | generate SGML for an applet sub sgml_for_usage { my $name = shift; my $usage = shift; @@ -93,10 +107,14 @@ sub sgml_for_usage { # { # trivial => "...", # full => "...", +# notes => "...", +# example => "...", # } my %docs; + # get command-line options + my %opt; GetOptions( @@ -118,33 +136,35 @@ if (defined $opt{help}) { exit 1; } + # collect documenation into %docs + foreach (@ARGV) { - open(USAGE, $_) || die("$0: $!"); + open(USAGE, $_) || die("$0: $_: $!"); my $fh = *USAGE; my ($applet, $type, @line); while (<$fh>) { - if (/^#define (\w+)_(\w+)_usage/) { $applet = $1; $type = $2; @line = continuation($fh); my $doc = $docs{$applet} ||= { }; - my $text = join("\n", @line); $doc->{$type} = beautify($text); } - } } + +# generate structured documentation + my $generator = \&pod_for_usage; if (defined $opt{sgml}) { - $generator = \&sgml_for_usage; + $generator = \&sgml_for_usage; } -foreach my $name (sort keys %docs) { - print $generator->($name, $docs{$name}); +foreach my $applet (sort keys %docs) { + print $generator->($applet, $docs{$applet}); } exit 0; @@ -157,40 +177,101 @@ autodocifier.pl - generate docs for busybox based on usage.h =head1 SYNOPSIS -autodocifier.pl usage.h > something +autodocifier.pl [OPTION]... [FILE]... + +Example: + + ( cat docs/busybox_header.pod; \ + docs/autodocifier.pl usage.h; \ + cat docs/busybox_footer.pod ) > docs/busybox.pod =head1 DESCRIPTION The purpose of this script is to automagically generate documentation for busybox using its usage.h as the original source for content. -Currently, the same content has to be duplicated in 3 places in +It used to be that same content has to be duplicated in 3 places in slightly different formats -- F, F, and -F. This is tedious, so Perl has come to the rescue. +F. This was tedious and error-prone, so it was +decided that F would contain all the text in a +machine-readable form, and scripts could be used to transform this +text into other forms if necessary. -This script was based on a script by Erik Andersen (andersen@lineo.com). +F is one such script. +It was based on a script by Erik Andersen +which was in turn based on a script by Mark Whitley =head1 OPTIONS =over 4 -=item --help +=item B<--help> This displays the help message. -=item --pod +=item B<--pod> Generate POD (this is the default) -=item --sgml +=item B<--sgml> Generate SGML -=item --verbose +=item B<--verbose> Be verbose (not implemented) =back +=head1 FORMAT + +The following is an example of some data this script might parse. + + #define length_trivial_usage \ + "STRING" + #define length_full_usage \ + "Prints out the length of the specified STRING." + #define length_example_usage \ + "$ length Hello\n" \ + "5\n" + +Each entry is a cpp macro that defines a string. The macros are +named systematically in the form: + + $name_$type_usage + +$name is the name of the applet. $type can be "trivial", "full", "notes", +or "example". Every documentation macro must end with "_usage". + +The definition of the types is as follows: + +=over 4 + +=item B + +This should be a brief, one-line description of parameters that +the command expects. This will be displayed when B<-h> is issued to +a command. I + +=item B + +This should contain descriptions of each option. This will also +be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP +is disabled. I + +=item B + +This is documentation that is intended to go in the POD or SGML, but +not be printed when a B<-h> is given to a command. To see an example +of notes being used, see init_notes_usage in F. I + +=item B + +This should be an example of how the command is actually used. +This will not be printed when a B<-h> is given to a command -- it +will only be included in the POD or SGML documentation. I + +=back + =head1 FILES F @@ -203,8 +284,8 @@ terms as Perl itself. =head1 AUTHOR -John BEPPU +John BEPPU =cut -# $Id: autodocifier.pl,v 1.10 2001/02/23 17:55:03 beppu Exp $ +# $Id: autodocifier.pl,v 1.23 2001/10/31 04:29:18 beppu Exp $