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