summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorDenys Vlasenko2009-10-02 01:10:32 +0200
committerDenys Vlasenko2009-10-02 01:10:32 +0200
commitacabf8fcb86302e55e01f0a20d5ff9914791416a (patch)
treeb1eff7768689d003f5c72a1ab175b1af52019012 /docs
parent3a7034c27b7fa8f3f08e2ace769f165f46afa0e3 (diff)
downloadbusybox-acabf8fcb86302e55e01f0a20d5ff9914791416a.zip
busybox-acabf8fcb86302e55e01f0a20d5ff9914791416a.tar.gz
Update documentation generator so that it sucks less
Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>
Diffstat (limited to 'docs')
-rwxr-xr-xdocs/autodocifier.pl307
-rw-r--r--docs/busybox_header.pod2
2 files changed, 1 insertions, 308 deletions
diff --git a/docs/autodocifier.pl b/docs/autodocifier.pl
deleted file mode 100755
index e3ba5c9..0000000
--- a/docs/autodocifier.pl
+++ /dev/null
@@ -1,307 +0,0 @@
-#!/usr/bin/perl -w
-# vi: set sw=4 ts=4:
-
-use strict;
-use Getopt::Long;
-
-# collect lines continued with a '\' into an array
-sub continuation {
- my $fh = shift;
- my @line;
-
- while (<$fh>) {
- my $s = $_;
- $s =~ s/\\\s*$//;
- #$s =~ s/#.*$//;
- push @line, $s;
- last unless (/\\\s*$/);
- }
- return @line;
-}
-
-# regex && eval away unwanted strings from documentation
-sub beautify {
- my $text = shift;
- for (;;) {
- my $text2 = $text;
- $text =~ s/IF_NOT_\w+\(.*?"\s*\)//sxg;
- $text =~ s/IF_\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 {
- s/^\s*"//;
- s/"\s*$//;
- s/%/%%/g;
- s/\$/\\\$/g;
- s/\@/\\\@/g;
- eval qq[ sprintf(qq{$_}) ]
- } @line
- );
- return $text;
-}
-
-# generate POD for an applet
-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};
- 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", (defined $usage->{full} ? $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];
- if (($i+1) != $len && $f0[$i] !~ /^\s/ && $f0[$i+1] =~ /^\s/) {
- next if ($f0[$i] =~ /^$/);
- 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"
- : "";
-
- # 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"
- ;
-}
-
-# the keys are applet names, and
-# the values will contain hashrefs of the form:
-#
-# {
-# trivial => "...",
-# full => "...",
-# notes => "...",
-# example => "...",
-# }
-my %docs;
-
-
-# get command-line options
-
-my %opt;
-
-GetOptions(
- \%opt,
- "help|h",
- "pod|p",
- "verbose|v",
-);
-
-if (defined $opt{help}) {
- print
- "$0 [OPTION]... [FILE]...\n",
- "\t--help\n",
- "\t--pod\n",
- "\t--verbose\n",
- ;
- exit 1;
-}
-
-
-# collect documenation into %docs
-
-foreach (@ARGV) {
- 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;
-
-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 (@names) {
- print $generator->($applet, $docs{$applet});
-}
-
-exit 0;
-
-__END__
-
-=head1 NAME
-
-autodocifier.pl - generate docs for busybox based on usage.h
-
-=head1 SYNOPSIS
-
-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. 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.
-
-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
-
-=over 4
-
-=item B<--help>
-
-This displays the help message.
-
-=item B<--pod>
-
-Generate POD (this is the default)
-
-=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<trivial>
-
-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<REQUIRED>
-
-=item B<full>
-
-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<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 in F<usage.h>. I<OPTIONAL>
-
-=item B<example>
-
-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<OPTIONAL>
-
-=back
-
-=head1 FILES
-
-F<usage.h>
-
-=head1 COPYRIGHT
-
-Copyright (c) 2001 John BEPPU. All rights reserved. This program is
-free software; you can redistribute it and/or modify it under the same
-terms as Perl itself.
-
-=head1 AUTHOR
-
-John BEPPU <b@ax9.org>
-
-=cut
-
diff --git a/docs/busybox_header.pod b/docs/busybox_header.pod
index 9f2ffc4..2a99636 100644
--- a/docs/busybox_header.pod
+++ b/docs/busybox_header.pod
@@ -8,7 +8,7 @@ BusyBox - The Swiss Army Knife of Embedded Linux
busybox <applet> [arguments...] # or
- <applet> [arguments...] # if symlinked
+ <applet> [arguments...] # if symlinked
=head1 DESCRIPTION