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 { eval }
  30                 map { qq[ sprintf(qq#$_#) ] }
  31                 map {
  32                         s/^\s*//;
  33                         s/"//g;
  34                         s/% /%% /g;
  35                         $_
  36                 }
  37                 @line
  38         );
  39         print STDERR "-- d\n";
  40         print STDERR $text;
  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         my $trivial = $usage->{trivial};
  50         $trivial =~s/(?<!\w)(-\w+)/B<$1>/sxg;
  51
  52         my $full =
  53                 join("\n",
  54                 map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ }
  55                 split("\n", $usage->{full}));
  56
  57         return
  58                 "-------------------------------\n".
  59                 "\n".
  60                 "=item $name".
  61                 "\n\n".
  62                 "$name $trivial".
  63                 "\n\n".
  64                 $full.
  65                 "\n\n"
  66         ;
  67 }
  68
  69 # generate SGML for an applet
  70 sub sgml_for_usage {
  71         my $name  = shift;
  72         my $usage = shift;
  73         return
  74         "FIXME";
  75 }
  76
  77 # the keys are applet names, and
  78 # the values will contain hashrefs of the form:
  79 #
  80 # {
  81 #     trivial => "...",
  82 #     full    => "...",
  83 # }
  84 my %docs;
  85
  86 # get command-line options
  87 my %opt;
  88
  89 GetOptions(
  90         \%opt,
  91         "help|h",
  92         "sgml|s",
  93         "pod|p",
  94         "verbose|v",
  95 );
  96
  97 if (defined $opt{help}) {
  98         print
  99                 "$0 [OPTION]... [FILE]...\n",
 100                 "\t--help\n",
 101                 "\t--sgml\n",
 102                 "\t--pod\n",
 103                 "\t--verbose\n",
 104         ;
 105         exit 1;
 106 }
 107
 108 # collect documenation into %docs
 109 foreach (@ARGV) {
 110         open(USAGE, $_) || die("$0: $!");
 111         my $fh = *USAGE;
 112         my ($applet, $type, @line);
 113         while (<$fh>) {
 114
 115                 if (/^#define (\w+)_(\w+)_usage/) {
 116                         $applet = $1;
 117                         $type   = $2;
 118                         @line   = continuation($fh);
 119                         my $doc = $docs{$applet} ||= { };
 120
 121                         my $text      = join("\n", @line);
 122                         $doc->{$type} = beautify($text);
 123                 }
 124
 125         }
 126 }
 127
 128 #use Data::Dumper;
 129 #print Data::Dumper->Dump([\%docs], [qw(docs)]);
 130
 131 foreach my $name (sort keys %docs) {
 132         print pod_for_usage($name, $docs{$name});
 133 }
 134
 135 exit 0;
 136
 137 __END__
 138
 139 =head1 NAME
 140
 141 autodocifier.pl - generate docs for busybox based on usage.h
 142
 143 =head1 SYNOPSIS
 144
 145 autodocifier.pl usage.h > something
 146
 147 =head1 DESCRIPTION
 148
 149 The purpose of this script is to automagically generate documentation
 150 for busybox using its usage.h as the original source for content.
 151 Currently, the same content has to be duplicated in 3 places in
 152 slightly different formats -- F<usage.h>, F<docs/busybox.pod>, and
 153 F<docs/busybox.sgml>.  This is tedious, so Perl has come to the rescue.
 154
 155 This script was based on a script by Erik Andersen (andersen@lineo.com).
 156
 157 =head1 OPTIONS
 158
 159 these control my behaviour
 160
 161 =over 8
 162
 163 =item --help
 164
 165 This displays the help message.
 166
 167 =back
 168
 169 =head1 FILES
 170
 171 files that I manipulate
 172
 173 =head1 COPYRIGHT
 174
 175 Copyright (c) 2001 John BEPPU.  All rights reserved.  This program is
 176 free software; you can redistribute it and/or modify it under the same
 177 terms as Perl itself.
 178
 179 =head1 AUTHOR
 180
 181 John BEPPU <beppu@lineo.com>
 182
 183 =cut
 184
 185 # $Id: autodocifier.pl,v 1.6 2001/02/23 16:15:34 beppu Exp $