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