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