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