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 $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg;
56 map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ }
57 split("\n", $usage->{full});
59 # add "\n" prior to certain lines to make indented
63 for (my $i = 0; $i < $len; $i++) {
65 if (($i+1) != $len && $f0[$i] !~ /^\s/ && $f0[$i+1] =~ /^\s/) {
66 next if ($f0[$i] =~ /^$/);
67 push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s);
70 my $full = join("\n", @f1);
72 # prepare notes if they exist
73 my $notes = (defined $usage->{notes})
74 ? "$usage->{notes}\n\n"
77 # prepare examples if they exist
78 my $example = (defined $usage->{example})
83 split("\n", $usage->{example})) . "\n\n"
88 "\n\n$name $trivial\n\n".
92 "-------------------------------".
97 # FIXME | generate SGML for an applet
108 # the keys are applet names, and
109 # the values will contain hashrefs of the form:
120 # get command-line options
132 if (defined $opt{help}) {
134 "$0 [OPTION]... [FILE]...\n",
144 # collect documenation into %docs
147 open(USAGE, $_) || die("$0: $_: $!");
149 my ($applet, $type, @line);
151 if (/^#define (\w+)_(\w+)_usage/) {
154 @line = continuation($fh);
155 my $doc = $docs{$applet} ||= { };
156 my $text = join("\n", @line);
157 $doc->{$type} = beautify($text);
163 # generate structured documentation
165 my $generator = \&pod_for_usage;
166 if (defined $opt{sgml}) {
167 $generator = \&sgml_for_usage;
170 foreach my $applet (sort keys %docs) {
171 print $generator->($applet, $docs{$applet});
180 autodocifier.pl - generate docs for busybox based on usage.h
184 autodocifier.pl [OPTION]... [FILE]...
188 ( cat docs/busybox_header.pod; \
189 docs/autodocifier.pl usage.h; \
190 cat docs/busybox_footer.pod ) > docs/busybox.pod
194 The purpose of this script is to automagically generate documentation
195 for busybox using its usage.h as the original source for content.
196 It used to be that same content has to be duplicated in 3 places in
197 slightly different formats -- F<usage.h>, F<docs/busybox.pod>, and
198 F<docs/busybox.sgml>. This was tedious and error-prone, so it was
199 decided that F<usage.h> would contain all the text in a
200 machine-readable form, and scripts could be used to transform this
201 text into other forms if necessary.
203 F<autodocifier.pl> is one such script.
204 It was based on a script by Erik Andersen <andersen@codepoet.org>
205 which was in turn based on a script by Mark Whitley <markw@codepoet.org>
213 This displays the help message.
217 Generate POD (this is the default)
225 Be verbose (not implemented)
231 The following is an example of some data this script might parse.
233 #define length_trivial_usage \
235 #define length_full_usage \
236 "Prints out the length of the specified STRING."
237 #define length_example_usage \
241 Each entry is a cpp macro that defines a string. The macros are
242 named systematically in the form:
246 $name is the name of the applet. $type can be "trivial", "full", "notes",
247 or "example". Every documentation macro must end with "_usage".
249 The definition of the types is as follows:
255 This should be a brief, one-line description of parameters that
256 the command expects. This will be displayed when B<-h> is issued to
257 a command. I<REQUIRED>
261 This should contain descriptions of each option. This will also
262 be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP
263 is disabled. I<REQUIRED>
267 This is documentation that is intended to go in the POD or SGML, but
268 not be printed when a B<-h> is given to a command. To see an example
269 of notes being used, see init_notes_usage in F<usage.h>. I<OPTIONAL>
273 This should be an example of how the command is actually used.
274 This will not be printed when a B<-h> is given to a command -- it
275 will only be included in the POD or SGML documentation. I<OPTIONAL>
285 Copyright (c) 2001 John BEPPU. All rights reserved. This program is
286 free software; you can redistribute it and/or modify it under the same
287 terms as Perl itself.
291 John BEPPU <b@ax9.org>
295 # $Id: autodocifier.pl,v 1.25 2004/03/13 08:32:14 andersen Exp $