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 my $line = "\t[, [[, ";
 159 for (my $i = 0; $i < $#names; $i++) {
 160         if (length ($line.$names[$i]) >= 65) {
 161                 print "$line\n\t";
 162                 $line = "";
 163         }
 164         $line .= "$names[$i], ";
 165 }
 166 print $line . $names[-1];
 167
 168 print "\n\n=head1 COMMAND DESCRIPTIONS\n";
 169 print "\n=over 4\n\n";
 170
 171 foreach my $applet (@names) {
 172         print $generator->($applet, $docs{$applet});
 173 }
 174
 175 exit 0;
 176
 177 __END__
 178
 179 =head1 NAME
 180
 181 autodocifier.pl - generate docs for busybox based on usage.h
 182
 183 =head1 SYNOPSIS
 184
 185 autodocifier.pl [OPTION]... [FILE]...
 186
 187 Example:
 188
 189     ( cat docs/busybox_header.pod; \
 190       docs/autodocifier.pl usage.h; \
 191       cat docs/busybox_footer.pod ) > docs/busybox.pod
 192
 193 =head1 DESCRIPTION
 194
 195 The purpose of this script is to automagically generate
 196 documentation for busybox using its usage.h as the original source
 197 for content.  It used to be that same content has to be duplicated
 198 in 3 places in slightly different formats -- F<usage.h>,
 199 F<docs/busybox.pod>.  This was tedious and error-prone, so it was
 200 decided that F<usage.h> would contain all the text in a
 201 machine-readable form, and scripts could be used to transform this
 202 text into other forms if necessary.
 203
 204 F<autodocifier.pl> is one such script.  It is based on a script by
 205 Erik Andersen <andersen@codepoet.org> which was in turn based on a
 206 script by Mark Whitley <markw@codepoet.org>
 207
 208 =head1 OPTIONS
 209
 210 =over 4
 211
 212 =item B<--help>
 213
 214 This displays the help message.
 215
 216 =item B<--pod>
 217
 218 Generate POD (this is the default)
 219
 220 =item B<--verbose>
 221
 222 Be verbose (not implemented)
 223
 224 =back
 225
 226 =head1 FORMAT
 227
 228 The following is an example of some data this script might parse.
 229
 230     #define length_trivial_usage \
 231             "STRING"
 232     #define length_full_usage \
 233             "Prints out the length of the specified STRING."
 234     #define length_example_usage \
 235             "$ length Hello\n" \
 236             "5\n"
 237
 238 Each entry is a cpp macro that defines a string.  The macros are
 239 named systematically in the form:
 240
 241     $name_$type_usage
 242
 243 $name is the name of the applet.  $type can be "trivial", "full", "notes",
 244 or "example".  Every documentation macro must end with "_usage".
 245
 246 The definition of the types is as follows:
 247
 248 =over 4
 249
 250 =item B<trivial>
 251
 252 This should be a brief, one-line description of parameters that
 253 the command expects.  This will be displayed when B<-h> is issued to
 254 a command.  I<REQUIRED>
 255
 256 =item B<full>
 257
 258 This should contain descriptions of each option.  This will also
 259 be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP
 260 is disabled.  I<REQUIRED>
 261
 262 =item B<notes>
 263
 264 This is documentation that is intended to go in the POD or SGML, but
 265 not be printed when a B<-h> is given to a command.  To see an example
 266 of notes being used, see init_notes_usage in F<usage.h>.  I<OPTIONAL>
 267
 268 =item B<example>
 269
 270 This should be an example of how the command is actually used.
 271 This will not be printed when a B<-h> is given to a command -- it
 272 will only be included in the POD or SGML documentation.  I<OPTIONAL>
 273
 274 =back
 275
 276 =head1 FILES
 277
 278 F<usage.h>
 279
 280 =head1 COPYRIGHT
 281
 282 Copyright (c) 2001 John BEPPU.  All rights reserved.  This program is
 283 free software; you can redistribute it and/or modify it under the same
 284 terms as Perl itself.
 285
 286 =head1 AUTHOR
 287
 288 John BEPPU <b@ax9.org>
 289
 290 =cut
 291
 292 # $Id: autodocifier.pl,v 1.26 2004/04/06 15:26:25 andersen Exp $