docs/autodocifier.pl

   1 #!/usr/bin/perl -w
   2
   3 use strict;
   4 use Getopt::Long;
   5
   6 # collect lines continued with a '\' into an array
   7 sub continuation {
   8         my $fh = shift;
   9         my @line;
  10
  11         while (<$fh>) {
  12                 my $s = $_;
  13                 $s =~ s/\\\s*$//;
  14                 #$s =~ s/#.*$//;
  15                 push @line, $s;
  16                 last unless (/\\\s*$/);
  17         }
  18         return @line;
  19 }
  20
  21 # regex && eval away unwanted strings from documentation
  22 sub beautify {
  23         my $text = shift;
  24         for (;;) {
  25                 my $text2 = $text;
  26                 $text =~ s/SKIP_\w+\(.*?"\s*\)//sxg;
  27                 $text =~ s/USE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg;
  28                 last if ( $text2 eq $text );
  29         }
  30         $text =~ s/"\s*"//sg;
  31         my @line = split("\n", $text);
  32         $text = join('',
  33                 map {
  34                         s/^\s*"//;
  35                         s/"\s*$//;
  36                         s/%/%%/g;
  37                         s/\$/\\\$/g;
  38                         eval qq[ sprintf(qq{$_}) ]
  39                 } @line
  40         );
  41         return $text;
  42 }
  43
  44 # generate POD for an applet
  45 sub pod_for_usage {
  46         my $name  = shift;
  47         my $usage = shift;
  48
  49         # Sigh.  Fixup the known odd-name applets.
  50         $name =~ s/dpkg_deb/dpkg-deb/g;
  51         $name =~ s/fsck_minix/fsck.minix/g;
  52         $name =~ s/mkfs_minix/mkfs.minix/g;
  53         $name =~ s/run_parts/run-parts/g;
  54         $name =~ s/start_stop_daemon/start-stop-daemon/g;
  55
  56         # make options bold
  57         my $trivial = $usage->{trivial};
  58         if (!defined $usage->{trivial}) {
  59                 $trivial = "";
  60         } else {
  61                 $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg;
  62         }
  63         my @f0 =
  64                 map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ }
  65                 split("\n", (defined $usage->{full} ? $usage->{full} : ""));
  66
  67         # add "\n" prior to certain lines to make indented
  68         # lines look right
  69         my @f1;
  70         my $len = @f0;
  71         for (my $i = 0; $i < $len; $i++) {
  72                 push @f1, $f0[$i];
  73                 if (($i+1) != $len && $f0[$i] !~ /^\s/ && $f0[$i+1] =~ /^\s/) {
  74                         next if ($f0[$i] =~ /^$/);
  75                         push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s);
  76                 }
  77         }
  78         my $full = join("\n", @f1);
  79
  80         # prepare notes if they exist
  81         my $notes = (defined $usage->{notes})
  82                 ? "$usage->{notes}\n\n"
  83                 : "";
  84
  85         # prepare examples if they exist
  86         my $example = (defined $usage->{example})
  87                 ?
  88                         "Example:\n\n" .
  89                         join ("\n",
  90                         map  { "\t$_" }
  91                         split("\n", $usage->{example})) . "\n\n"
  92                 : "";
  93
  94         # Pad the name so that the applet name gets a line
  95         # by itself in BusyBox.txt
  96         my $spaces = 10 - length($name);
  97         if ($spaces > 0) {
  98                 $name .= " " x $spaces;
  99         }
 100
 101         return
 102                 "=item B<$name>".
 103                 "\n\n$name $trivial\n\n".
 104                 "$full\n\n"   .
 105                 "$notes"  .
 106                 "$example" .
 107                 "\n\n"
 108         ;
 109 }
 110
 111 # the keys are applet names, and
 112 # the values will contain hashrefs of the form:
 113 #
 114 # {
 115 #     trivial => "...",
 116 #     full    => "...",
 117 #     notes   => "...",
 118 #     example => "...",
 119 # }
 120 my %docs;
 121
 122
 123 # get command-line options
 124
 125 my %opt;
 126
 127 GetOptions(
 128         \%opt,
 129         "help|h",
 130         "pod|p",
 131         "verbose|v",
 132 );
 133
 134 if (defined $opt{help}) {
 135         print
 136                 "$0 [OPTION]... [FILE]...\n",
 137                 "\t--help\n",
 138                 "\t--pod\n",
 139                 "\t--verbose\n",
 140         ;
 141         exit 1;
 142 }
 143
 144
 145 # collect documenation into %docs
 146
 147 foreach (@ARGV) {
 148         open(USAGE, $_) || die("$0: $_: $!");
 149         my $fh = *USAGE;
 150         my ($applet, $type, @line);
 151         while (<$fh>) {
 152                 if (/^#define (\w+)_(\w+)_usage/) {
 153                         $applet = $1;
 154                         $type   = $2;
 155                         @line   = continuation($fh);
 156                         my $doc = $docs{$applet} ||= { };
 157                         my $text      = join("\n", @line);
 158                         $doc->{$type} = beautify($text);
 159                 }
 160         }
 161 }
 162
 163
 164 # generate structured documentation
 165
 166 my $generator = \&pod_for_usage;
 167
 168 my @names = sort keys %docs;
 169 my $line = "\t[, [[, ";
 170 for (my $i = 0; $i < $#names; $i++) {
 171         if (length ($line.$names[$i]) >= 65) {
 172                 print "$line\n\t";
 173                 $line = "";
 174         }
 175         $line .= "$names[$i], ";
 176 }
 177 print $line . $names[-1];
 178
 179 print "\n\n=head1 COMMAND DESCRIPTIONS\n";
 180 print "\n=over 4\n\n";
 181
 182 foreach my $applet (@names) {
 183         print $generator->($applet, $docs{$applet});
 184 }
 185
 186 exit 0;
 187
 188 __END__
 189
 190 =head1 NAME
 191
 192 autodocifier.pl - generate docs for busybox based on usage.h
 193
 194 =head1 SYNOPSIS
 195
 196 autodocifier.pl [OPTION]... [FILE]...
 197
 198 Example:
 199
 200     ( cat docs/busybox_header.pod; \
 201       docs/autodocifier.pl usage.h; \
 202       cat docs/busybox_footer.pod ) > docs/busybox.pod
 203
 204 =head1 DESCRIPTION
 205
 206 The purpose of this script is to automagically generate
 207 documentation for busybox using its usage.h as the original source
 208 for content.  It used to be that same content has to be duplicated
 209 in 3 places in slightly different formats -- F<usage.h>,
 210 F<docs/busybox.pod>.  This was tedious and error-prone, so it was
 211 decided that F<usage.h> would contain all the text in a
 212 machine-readable form, and scripts could be used to transform this
 213 text into other forms if necessary.
 214
 215 F<autodocifier.pl> is one such script.  It is based on a script by
 216 Erik Andersen <andersen@codepoet.org> which was in turn based on a
 217 script by Mark Whitley <markw@codepoet.org>
 218
 219 =head1 OPTIONS
 220
 221 =over 4
 222
 223 =item B<--help>
 224
 225 This displays the help message.
 226
 227 =item B<--pod>
 228
 229 Generate POD (this is the default)
 230
 231 =item B<--verbose>
 232
 233 Be verbose (not implemented)
 234
 235 =back
 236
 237 =head1 FORMAT
 238
 239 The following is an example of some data this script might parse.
 240
 241     #define length_trivial_usage \
 242             "STRING"
 243     #define length_full_usage \
 244             "Prints out the length of the specified STRING."
 245     #define length_example_usage \
 246             "$ length Hello\n" \
 247             "5\n"
 248
 249 Each entry is a cpp macro that defines a string.  The macros are
 250 named systematically in the form:
 251
 252     $name_$type_usage
 253
 254 $name is the name of the applet.  $type can be "trivial", "full", "notes",
 255 or "example".  Every documentation macro must end with "_usage".
 256
 257 The definition of the types is as follows:
 258
 259 =over 4
 260
 261 =item B<trivial>
 262
 263 This should be a brief, one-line description of parameters that
 264 the command expects.  This will be displayed when B<-h> is issued to
 265 a command.  I<REQUIRED>
 266
 267 =item B<full>
 268
 269 This should contain descriptions of each option.  This will also
 270 be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP
 271 is disabled.  I<REQUIRED>
 272
 273 =item B<notes>
 274
 275 This is documentation that is intended to go in the POD or SGML, but
 276 not be printed when a B<-h> is given to a command.  To see an example
 277 of notes being used, see init_notes_usage in F<usage.h>.  I<OPTIONAL>
 278
 279 =item B<example>
 280
 281 This should be an example of how the command is actually used.
 282 This will not be printed when a B<-h> is given to a command -- it
 283 will only be included in the POD or SGML documentation.  I<OPTIONAL>
 284
 285 =back
 286
 287 =head1 FILES
 288
 289 F<usage.h>
 290
 291 =head1 COPYRIGHT
 292
 293 Copyright (c) 2001 John BEPPU.  All rights reserved.  This program is
 294 free software; you can redistribute it and/or modify it under the same
 295 terms as Perl itself.
 296
 297 =head1 AUTHOR
 298
 299 John BEPPU <b@ax9.org>
 300
 301 =cut
 302
 303 # $Id: autodocifier.pl,v 1.26 2004/04/06 15:26:25 andersen Exp $