6 # collect lines continued with a '\' into an array
16 last unless (/\\\s*$/);
21 # regex && eval away unwanted strings from documentation
24 $text =~ s/USAGE_NOT\w+\(.*?"\s*\)//sxg;
25 $text =~ s/USAGE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg;
27 my @line = split("\n", $text);
34 eval qq[ sprintf(qq{$_}) ]
40 # generate POD for an applet
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;
53 my $trivial = $usage->{trivial};
54 if (!defined $usage->{trivial}) {
57 $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg;
60 map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ }
61 split("\n", (defined $usage->{full} ? $usage->{full} : ""));
63 # add "\n" prior to certain lines to make indented
67 for (my $i = 0; $i < $len; $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);
74 my $full = join("\n", @f1);
76 # prepare notes if they exist
77 my $notes = (defined $usage->{notes})
78 ? "$usage->{notes}\n\n"
81 # prepare examples if they exist
82 my $example = (defined $usage->{example})
87 split("\n", $usage->{example})) . "\n\n"
90 # Pad the name so that the applet name gets a line
91 # by itself in BusyBox.txt
92 my $spaces = 10 - length($name);
94 $name .= " " x $spaces;
99 "\n\n$name $trivial\n\n".
107 # the keys are applet names, and
108 # the values will contain hashrefs of the form:
119 # get command-line options
130 if (defined $opt{help}) {
132 "$0 [OPTION]... [FILE]...\n",
141 # collect documenation into %docs
144 open(USAGE, $_) || die("$0: $_: $!");
146 my ($applet, $type, @line);
148 if (/^#define (\w+)_(\w+)_usage/) {
151 @line = continuation($fh);
152 my $doc = $docs{$applet} ||= { };
153 my $text = join("\n", @line);
154 $doc->{$type} = beautify($text);
160 # generate structured documentation
162 my $generator = \&pod_for_usage;
164 my @names = sort keys %docs;
165 my $line = "\t[, [[, ";
166 for (my $i = 0; $i < $#names; $i++) {
167 if (length ($line.$names[$i]) >= 65) {
171 $line .= "$names[$i], ";
173 print $line . $names[-1];
175 print "\n\n=head1 COMMAND DESCRIPTIONS\n";
176 print "\n=over 4\n\n";
178 foreach my $applet (@names) {
179 print $generator->($applet, $docs{$applet});
188 autodocifier.pl - generate docs for busybox based on usage.h
192 autodocifier.pl [OPTION]... [FILE]...
196 ( cat docs/busybox_header.pod; \
197 docs/autodocifier.pl usage.h; \
198 cat docs/busybox_footer.pod ) > docs/busybox.pod
202 The purpose of this script is to automagically generate
203 documentation for busybox using its usage.h as the original source
204 for content. It used to be that same content has to be duplicated
205 in 3 places in slightly different formats -- F<usage.h>,
206 F<docs/busybox.pod>. This was tedious and error-prone, so it was
207 decided that F<usage.h> would contain all the text in a
208 machine-readable form, and scripts could be used to transform this
209 text into other forms if necessary.
211 F<autodocifier.pl> is one such script. It is based on a script by
212 Erik Andersen <andersen@codepoet.org> which was in turn based on a
213 script by Mark Whitley <markw@codepoet.org>
221 This displays the help message.
225 Generate POD (this is the default)
229 Be verbose (not implemented)
235 The following is an example of some data this script might parse.
237 #define length_trivial_usage \
239 #define length_full_usage \
240 "Prints out the length of the specified STRING."
241 #define length_example_usage \
245 Each entry is a cpp macro that defines a string. The macros are
246 named systematically in the form:
250 $name is the name of the applet. $type can be "trivial", "full", "notes",
251 or "example". Every documentation macro must end with "_usage".
253 The definition of the types is as follows:
259 This should be a brief, one-line description of parameters that
260 the command expects. This will be displayed when B<-h> is issued to
261 a command. I<REQUIRED>
265 This should contain descriptions of each option. This will also
266 be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP
267 is disabled. I<REQUIRED>
271 This is documentation that is intended to go in the POD or SGML, but
272 not be printed when a B<-h> is given to a command. To see an example
273 of notes being used, see init_notes_usage in F<usage.h>. I<OPTIONAL>
277 This should be an example of how the command is actually used.
278 This will not be printed when a B<-h> is given to a command -- it
279 will only be included in the POD or SGML documentation. I<OPTIONAL>
289 Copyright (c) 2001 John BEPPU. All rights reserved. This program is
290 free software; you can redistribute it and/or modify it under the same
291 terms as Perl itself.
295 John BEPPU <b@ax9.org>
299 # $Id: autodocifier.pl,v 1.26 2004/04/06 15:26:25 andersen Exp $