Added a compile time option to suppress the "Using fallback.." message

[oweals/busybox.git] / docs / autodocifier.pl

diff --git a/docs/autodocifier.pl b/docs/autodocifier.pl
index 2d5e04a2ed03153c30c86aa1f77c37f7dabc1d1f..377c8b55b385c524128730d7667b16f9974ee346 100755 (executable)
--- 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*$/);
        }
@@ -27,11 +27,11 @@ sub beautify {
        my @line = split("\n", $text);
        $text = join('',
                map { 
-                       s/^\s*//;
-                       s/"//g;
+                       s/^\s*"//;
+                       s/"\s*$//;
                        s/%/%%/g;
                        s/\$/\\\$/g;
-                       eval qq[ sprintf(qq#$_#) ]
+                       eval qq[ sprintf(qq{$_}) ]
                } @line
        );
        return $text;
@@ -62,18 +62,28 @@ sub pod_for_usage {
        }
        my $full = join("\n", @f1);
 
-       # prepare example if one exists
+       # 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$usage->{example}\n\n"
+               ?  
+                       "Example:\n\n" .
+                       join ("\n", 
+                       map  { "\t$_" } 
+                       split("\n", $usage->{example})) . "\n\n"
                : "";
 
        return
-               "=item I<$name>".
+               "=item B<$name>".
                "\n\n"  .
                "$name $trivial".
                "\n\n"  .
                $full   .
                "\n\n"  .
+               $notes  .
                $example.
                "-------------------------------".
                "\n\n"
@@ -97,6 +107,8 @@ sub sgml_for_usage {
 # {
 #     trivial => "...",
 #     full    => "...",
+#     notes   => "...",
+#     example => "...",
 # }
 my %docs;
 
@@ -137,7 +149,6 @@ foreach (@ARGV) {
                        $type   = $2;
                        @line   = continuation($fh);
                        my $doc = $docs{$applet} ||= { };
-
                        my $text      = join("\n", @line);
                        $doc->{$type} = beautify($text);
                }
@@ -166,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<usage.h>, F<docs/busybox.pod>, and
-F<docs/busybox.sgml>.  This is tedious, so Perl has come to the rescue.
+F<docs/busybox.sgml>.  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).
+F<autodocifier.pl> is one such script.
+It 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>
 
 =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<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>
@@ -212,8 +284,8 @@ terms as Perl itself.
 
 =head1 AUTHOR
 
-John BEPPU <beppu@lineo.com>
+John BEPPU <b@ax9.org>
 
 =cut
 
-# $Id: autodocifier.pl,v 1.13 2001/02/26 02:50:11 beppu Exp $
+# $Id: autodocifier.pl,v 1.23 2001/10/31 04:29:18 beppu Exp $