source: MondoRescue/branches/stable/mindi-busybox/docs/autodocifier.pl @ 821

Last change on this file since 821 was 821, checked in by Bruno Cornec, 14 years ago

Addition of busybox 1.2.1 as a mindi-busybox new package
This should avoid delivering binary files in mindi not built there (Fedora and Debian are quite serious about that)

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