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