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         $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg;
  55         my @f0 =
  56                 map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ }
  57                 split("\n", $usage->{full});
  58
  59         # add "\n" prior to certain lines to make indented
  60         # lines look right
  61         my @f1;
  62         my $len = @f0;
  63         for (my $i = 0; $i < $len; $i++) {
  64                 push @f1, $f0[$i];
  65                 if (($i+1) != $len && $f0[$i] !~ /^\s/ && $f0[$i+1] =~ /^\s/) {
  66                         next if ($f0[$i] =~ /^$/);
  67                         push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s);
  68                 }
  69         }
  70         my $full = join("\n", @f1);
  71
  72         # prepare notes if they exist
  73         my $notes = (defined $usage->{notes})
  74                 ? "$usage->{notes}\n\n"
  75                 : "";
  76
  77         # prepare examples if they exist
  78         my $example = (defined $usage->{example})
  79                 ?
  80                         "Example:\n\n" .
  81                         join ("\n",
  82                         map  { "\t$_" }
  83                         split("\n", $usage->{example})) . "\n\n"
  84                 : "";
  85
  86         return
  87                 "=item B<$name>".
  88                 "\n\n$name $trivial\n\n".
  89                 "$full\n\n"   .
  90                 "$notes"  .
  91                 "$example" .
  92                 "-------------------------------".
  93                 "\n\n"
  94         ;
  95 }
  96
  97 # FIXME | generate SGML for an applet
  98 sub sgml_for_usage {
  99         my $name  = shift;
 100         my $usage = shift;
 101         return
 102                 "<fixme>\n".
 103                 "  $name\n".
 104                 "</fixme>\n"
 105         ;
 106 }
 107
 108 # the keys are applet names, and
 109 # the values will contain hashrefs of the form:
 110 #
 111 # {
 112 #     trivial => "...",
 113 #     full    => "...",
 114 #     notes   => "...",
 115 #     example => "...",
 116 # }
 117 my %docs;
 118
 119
 120 # get command-line options
 121
 122 my %opt;
 123
 124 GetOptions(
 125         \%opt,
 126         "help|h",
 127         "sgml|s",
 128         "pod|p",
 129         "verbose|v",
 130 );
 131
 132 if (defined $opt{help}) {
 133         print
 134                 "$0 [OPTION]... [FILE]...\n",
 135                 "\t--help\n",
 136                 "\t--sgml\n",
 137                 "\t--pod\n",
 138                 "\t--verbose\n",
 139         ;
 140         exit 1;
 141 }
 142
 143
 144 # collect documenation into %docs
 145
 146 foreach (@ARGV) {
 147         open(USAGE, $_) || die("$0: $_: $!");
 148         my $fh = *USAGE;
 149         my ($applet, $type, @line);
 150         while (<$fh>) {
 151                 if (/^#define (\w+)_(\w+)_usage/) {
 152                         $applet = $1;
 153                         $type   = $2;
 154                         @line   = continuation($fh);
 155                         my $doc = $docs{$applet} ||= { };
 156                         my $text      = join("\n", @line);
 157                         $doc->{$type} = beautify($text);
 158                 }
 159         }
 160 }
 161
 162
 163 # generate structured documentation
 164
 165 my $generator = \&pod_for_usage;
 166 if (defined $opt{sgml}) {
 167         $generator = \&sgml_for_usage;
 168 }
 169
 170 foreach my $applet (sort keys %docs) {
 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 documentation
 195 for busybox using its usage.h as the original source for content.
 196 It used to be that same content has to be duplicated in 3 places in
 197 slightly different formats -- F<usage.h>, F<docs/busybox.pod>, and
 198 F<docs/busybox.sgml>.  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.
 204 It was based on a script by Erik Andersen <andersen@codepoet.org>
 205 which was in turn based on a 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<--sgml>
 220
 221 Generate SGML
 222
 223 =item B<--verbose>
 224
 225 Be verbose (not implemented)
 226
 227 =back
 228
 229 =head1 FORMAT
 230
 231 The following is an example of some data this script might parse.
 232
 233     #define length_trivial_usage \
 234             "STRING"
 235     #define length_full_usage \
 236             "Prints out the length of the specified STRING."
 237     #define length_example_usage \
 238             "$ length Hello\n" \
 239             "5\n"
 240
 241 Each entry is a cpp macro that defines a string.  The macros are
 242 named systematically in the form:
 243
 244     $name_$type_usage
 245
 246 $name is the name of the applet.  $type can be "trivial", "full", "notes",
 247 or "example".  Every documentation macro must end with "_usage".
 248
 249 The definition of the types is as follows:
 250
 251 =over 4
 252
 253 =item B<trivial>
 254
 255 This should be a brief, one-line description of parameters that
 256 the command expects.  This will be displayed when B<-h> is issued to
 257 a command.  I<REQUIRED>
 258
 259 =item B<full>
 260
 261 This should contain descriptions of each option.  This will also
 262 be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP
 263 is disabled.  I<REQUIRED>
 264
 265 =item B<notes>
 266
 267 This is documentation that is intended to go in the POD or SGML, but
 268 not be printed when a B<-h> is given to a command.  To see an example
 269 of notes being used, see init_notes_usage in F<usage.h>.  I<OPTIONAL>
 270
 271 =item B<example>
 272
 273 This should be an example of how the command is actually used.
 274 This will not be printed when a B<-h> is given to a command -- it
 275 will only be included in the POD or SGML documentation.  I<OPTIONAL>
 276
 277 =back
 278
 279 =head1 FILES
 280
 281 F<usage.h>
 282
 283 =head1 COPYRIGHT
 284
 285 Copyright (c) 2001 John BEPPU.  All rights reserved.  This program is
 286 free software; you can redistribute it and/or modify it under the same
 287 terms as Perl itself.
 288
 289 =head1 AUTHOR
 290
 291 John BEPPU <b@ax9.org>
 292
 293 =cut
 294
 295 # $Id: autodocifier.pl,v 1.25 2004/03/13 08:32:14 andersen Exp $