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
46 my $trivial = $usage->{trivial};
47 $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg;
49 map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ }
50 split("\n", $usage->{full});
52 # add "\n" prior to certain lines to make indented
56 for (my $i = 0; $i < $len; $i++) {
58 if (($i+1) != $len && $f0[$i] !~ /^\s/ && $f0[$i+1] =~ /^\s/) {
59 next if ($f0[$i] =~ /^$/);
60 push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s);
63 my $full = join("\n", @f1);
65 # prepare notes if they exist
66 my $notes = (defined $usage->{notes})
67 ? "$usage->{notes}\n\n"
70 # prepare examples if they exist
71 my $example = (defined $usage->{example})
76 split("\n", $usage->{example})) . "\n\n"
88 "-------------------------------".
93 # FIXME | generate SGML for an applet
104 # the keys are applet names, and
105 # the values will contain hashrefs of the form:
116 # get command-line options
128 if (defined $opt{help}) {
130 "$0 [OPTION]... [FILE]...\n",
140 # collect documenation into %docs
143 open(USAGE, $_) || die("$0: $_: $!");
145 my ($applet, $type, @line);
147 if (/^#define (\w+)_(\w+)_usage/) {
150 @line = continuation($fh);
151 my $doc = $docs{$applet} ||= { };
152 my $text = join("\n", @line);
153 $doc->{$type} = beautify($text);
159 # generate structured documentation
161 my $generator = \&pod_for_usage;
162 if (defined $opt{sgml}) {
163 $generator = \&sgml_for_usage;
166 foreach my $applet (sort keys %docs) {
167 print $generator->($applet, $docs{$applet});
176 autodocifier.pl - generate docs for busybox based on usage.h
180 autodocifier.pl [OPTION]... [FILE]...
184 ( cat docs/busybox_header.pod; \
185 docs/autodocifier.pl usage.h; \
186 cat docs/busybox_footer.pod ) > docs/busybox.pod
190 The purpose of this script is to automagically generate documentation
191 for busybox using its usage.h as the original source for content.
192 It used to be that same content has to be duplicated in 3 places in
193 slightly different formats -- F<usage.h>, F<docs/busybox.pod>, and
194 F<docs/busybox.sgml>. This was tedious and error-prone, so it was
195 decided that F<usage.h> would contain all the text in a
196 machine-readable form, and scripts could be used to transform this
197 text into other forms if necessary.
199 F<autodocifier.pl> is one such script.
200 It was based on a script by Erik Andersen <andersen@codepoet.org>
201 which was in turn based on a script by Mark Whitley <markw@codepoet.org>
209 This displays the help message.
213 Generate POD (this is the default)
221 Be verbose (not implemented)
227 The following is an example of some data this script might parse.
229 #define length_trivial_usage \
231 #define length_full_usage \
232 "Prints out the length of the specified STRING."
233 #define length_example_usage \
237 Each entry is a cpp macro that defines a string. The macros are
238 named systematically in the form:
242 $name is the name of the applet. $type can be "trivial", "full", "notes",
243 or "example". Every documentation macro must end with "_usage".
245 The definition of the types is as follows:
251 This should be a brief, one-line description of parameters that
252 the command expects. This will be displayed when B<-h> is issued to
253 a command. I<REQUIRED>
257 This should contain descriptions of each option. This will also
258 be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP
259 is disabled. I<REQUIRED>
263 This is documentation that is intended to go in the POD or SGML, but
264 not be printed when a B<-h> is given to a command. To see an example
265 of notes being used, see init_notes_usage in F<usage.h>. I<OPTIONAL>
269 This should be an example of how the command is actually used.
270 This will not be printed when a B<-h> is given to a command -- it
271 will only be included in the POD or SGML documentation. I<OPTIONAL>
281 Copyright (c) 2001 John BEPPU. All rights reserved. This program is
282 free software; you can redistribute it and/or modify it under the same
283 terms as Perl itself.
287 John BEPPU <b@ax9.org>
291 # $Id: autodocifier.pl,v 1.24 2003/07/14 21:20:48 andersen Exp $