diff options
Diffstat (limited to 'release/src/router/busybox/docs/autodocifier.pl')
| -rwxr-xr-x | release/src/router/busybox/docs/autodocifier.pl | 124 |
1 files changed, 72 insertions, 52 deletions
diff --git a/release/src/router/busybox/docs/autodocifier.pl b/release/src/router/busybox/docs/autodocifier.pl index 5f5ad792..576e3128 100755 --- a/release/src/router/busybox/docs/autodocifier.pl +++ b/release/src/router/busybox/docs/autodocifier.pl @@ -1,9 +1,10 @@ #!/usr/bin/perl -w +# vi: set sw=4 ts=4: use strict; use Getopt::Long; -# collect lines continued with a '\' into an array +# collect lines continued with a '\' into an array sub continuation { my $fh = shift; my @line; @@ -21,16 +22,22 @@ sub continuation { # regex && eval away unwanted strings from documentation sub beautify { my $text = shift; - $text =~ s/USAGE_NOT\w+\(.*?"\s*\)//sxg; - $text =~ s/USAGE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; + for (;;) { + my $text2 = $text; + $text =~ s/SKIP_\w+\(.*?"\s*\)//sxg; + $text =~ s/USE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; + $text =~ s/USAGE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; + last if ( $text2 eq $text ); + } $text =~ s/"\s*"//sg; my @line = split("\n", $text); $text = join('', - map { + map { s/^\s*"//; s/"\s*$//; s/%/%%/g; s/\$/\\\$/g; + s/\@/\\\@/g; eval qq[ sprintf(qq{$_}) ] } @line ); @@ -42,12 +49,25 @@ sub pod_for_usage { my $name = shift; my $usage = shift; + # Sigh. Fixup the known odd-name applets. +# Perhaps we can use some of APPLET_ODDNAME from include/applets.h ? + $name =~ s/dpkg_deb/dpkg-deb/g; + $name =~ s/fsck_minix/fsck.minix/g; + $name =~ s/mkfs_minix/mkfs.minix/g; + $name =~ s/run_parts/run-parts/g; + $name =~ s/start_stop_daemon/start-stop-daemon/g; + $name =~ s/ether_wake/ether-wake/g; + # make options bold my $trivial = $usage->{trivial}; - $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg; - my @f0 = + if (!defined $usage->{trivial}) { + $trivial = ""; + } else { + $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg; + } + my @f0 = map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ } - split("\n", $usage->{full}); + split("\n", (defined $usage->{full} ? $usage->{full} : "")); # add "\n" prior to certain lines to make indented # lines look right @@ -69,39 +89,31 @@ sub pod_for_usage { # prepare examples if they exist my $example = (defined $usage->{example}) - ? + ? "Example:\n\n" . - join ("\n", - map { "\t$_" } + join ("\n", + map { "\t$_" } split("\n", $usage->{example})) . "\n\n" : ""; + # Pad the name so that the applet name gets a line + # by itself in BusyBox.txt + my $spaces = 10 - length($name); + if ($spaces > 0) { + $name .= " " x $spaces; + } + return "=item B<$name>". - "\n\n" . - "$name $trivial". - "\n\n" . - $full . - "\n\n" . - $notes . - $example. - "-------------------------------". + "\n\n$name $trivial\n\n". + "$full\n\n" . + "$notes" . + "$example" . "\n\n" ; } -# FIXME | generate SGML for an applet -sub sgml_for_usage { - my $name = shift; - my $usage = shift; - return - "<fixme>\n". - " $name\n". - "</fixme>\n" - ; -} - -# the keys are applet names, and +# the keys are applet names, and # the values will contain hashrefs of the form: # # { @@ -120,7 +132,6 @@ my %opt; GetOptions( \%opt, "help|h", - "sgml|s", "pod|p", "verbose|v", ); @@ -129,7 +140,6 @@ if (defined $opt{help}) { print "$0 [OPTION]... [FILE]...\n", "\t--help\n", - "\t--sgml\n", "\t--pod\n", "\t--verbose\n", ; @@ -159,11 +169,22 @@ foreach (@ARGV) { # generate structured documentation my $generator = \&pod_for_usage; -if (defined $opt{sgml}) { - $generator = \&sgml_for_usage; + +my @names = sort keys %docs; +my $line = "\t[, [[, "; +for (my $i = 0; $i < $#names; $i++) { + if (length ($line.$names[$i]) >= 65) { + print "$line\n\t"; + $line = ""; + } + $line .= "$names[$i], "; } +print $line . $names[-1]; + +print "\n\n=head1 COMMAND DESCRIPTIONS\n"; +print "\n=over 4\n\n"; -foreach my $applet (sort keys %docs) { +foreach my $applet (@names) { print $generator->($applet, $docs{$applet}); } @@ -187,14 +208,18 @@ Example: =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 -slightly different formats -- F<usage.h>, F<docs/busybox.pod>, and -F<docs/busybox.sgml>. This is tedious, so Perl has come to the rescue. +The purpose of this script is to automagically generate +documentation for busybox using its usage.h as the original source +for content. It used to be that same content has to be duplicated +in 3 places in slightly different formats -- F<usage.h>, +F<docs/busybox.pod>. This was tedious and error-prone, so it was +decided that F<usage.h> 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> -which was in turn based on a script by Mark Whitley <markw@lineo.com> +F<autodocifier.pl> is one such script. It is based on a script by +Erik Andersen <andersen@codepoet.org> which was in turn based on a +script by Mark Whitley <markw@codepoet.org> =head1 OPTIONS @@ -208,10 +233,6 @@ This displays the help message. Generate POD (this is the default) -=item B<--sgml> - -Generate SGML - =item B<--verbose> Be verbose (not implemented) @@ -251,20 +272,20 @@ a command. I<REQUIRED> =item B<full> This should contain descriptions of each option. This will also -be displayed along with the trivial help if BB_FEATURE_TRIVIAL_HELP +be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP is disabled. I<REQUIRED> =item B<notes> 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. I<OPTIONAL> +of notes being used, see init_notes_usage in F<usage.h>. I<OPTIONAL> =item B<example> -This should be an example of how the command is acutally used. +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 -is inteded only for the POD or SGML documentation. I<OPTIONAL> +will only be included in the POD or SGML documentation. I<OPTIONAL> =back @@ -280,8 +301,7 @@ terms as Perl itself. =head1 AUTHOR -John BEPPU <beppu@lineo.com> +John BEPPU <b@ax9.org> =cut -# $Id: autodocifier.pl,v 1.1.1.4 2003/10/14 08:09:39 sparq Exp $ |