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

Last change on this file since 1770 was 1770, checked in by Bruno Cornec, 13 years ago
  • Better output for mindi-busybox revision
  • Remove dummy file created on NFS - report from Arnaud Tiger <arnaud.tiger_at_hp.com>
  • strace useful for debug
  • fix new versions for pb (2.0.0 for mindi and 1.7.2 for mindi-busybox)
  • fix build process for mindi-busybox + options used in that version (dd for label-partitions-as-necessary)
  • fix typo in label-partitions-as-necessary which doesn't seem to work
  • Update to busybox 1.7.2
  • perl is now required at restore time to support uuid swap partitions (and will be used for many other thigs

in the future for sure)

  • next mindi version will be 2.0.0 due to all the changes made in it (udev may break working distros)
  • small optimization in mindi on keyboard handling (one single find instead of multiple)
  • better interaction for USB device when launching mindi manually
  • attempt to automatically guess block disk size for ramdisk
  • fix typos in bkphw
  • Fix the remaining problem with UUID support for swap partitions
  • Updates mondoarchive man page for USB support
  • Adds preliminary Hardware support to mindi (Proliant SSSTK)
  • Tries to add udev support also for rhel4
  • Fix UUID support which was still broken.
  • Be conservative in test for the start-nfs script
  • Update config file for mindi-busybox for 1.7.2 migration
  • Try to run around a busybox bug (1.2.2 pb on inexistant links)
  • Add build content for mindi-busybox in pb
  • Remove distributions content for mindi-busybox
  • Fix a warning on inexistant raidtab
  • Solve problem on tmpfs in restore init (Problem of inexistant symlink and busybox)
  • Create MONDO_CACHE and use it everywhere + creation at start
  • Really never try to eject a USB device
  • Fix a issue with &> usage (replaced with 1> and 2>)
  • Adds magic file to depllist in order to have file working + ldd which helps for debugging issues
  • tty modes correct to avoid sh error messages
  • Use ext3 normally and not ext2 instead
  • USB device should be corrected after reading (take 1st part)
  • Adds a mount_USB_here function derived from mount_CDROM_here
  • usb detection place before /dev detection in device name at restore time
  • Fix when restoring from USB: media is asked in interactive mode
  • Adds USB support for mondorestore
  • mount_cdrom => mount_media
  • elilo.efi is now searched throughout /boot/efi and not in a fixed place as there is no standard
  • untar-and-softlink => untar (+ interface change)
  • suppress useless softlinks creation/removal in boot process
  • avoids udevd messages on groups
  • Increase # of disks to 99 as in mindi at restore time (should be a conf file parameter)
  • skip existing big file creation
  • seems to work correctly for USB mindi boot
  • Adds group and tty link to udev conf
  • Always load usb-torage (even 2.6) to initiate USB bus discovery
  • Better printing of messages
  • Attempt to fix a bug in supporting OpenSusE 10.3 kernel for initramfs (mindi may now use multiple regex for kernel initrd detection)
  • Links were not correctly done as non relative for modules in mindi
  • exclusion of modules denied now works
  • Also create modules in their ordinary place, so that classical modprobe works + copy modules.dep
  • Fix bugs for DENY_MODS handling
  • Add device /dev/console for udev
  • ide-generic should now really be excluded
  • Fix a bug in major number for tty
  • If udev then adds modprobe/insmod to rootfs
  • tty0 is also cretaed with udev
  • ide-generic put rather in DENY_MODS
  • udevd remove from deplist s handled in mindi directly
  • better default for mindi when using --usb
  • Handles dynamically linked busybox (in case we want to use it soon ;-)
  • Adds fixed devices to create for udev
  • ide-generic should not be part of the initrd when using libata v2
  • support a dynamically linked udev (case on Ubuntu 7.10 and Mandriva 2008.0 so should be quite generic) This will give incitation to move to dyn. linked binaries in the initrd which will help for other tasks (ia6 4)
  • Improvement in udev support (do not use cl options not available in busybox)
  • Udev in mindi
    • auto creation of the right links at boot time with udev-links.conf(from Mandriva 2008.0)
    • rework startup of udev as current makes kernel crash (from Mandriva 2008.0)
    • add support for 64 bits udev
  • Try to render MyInsmod? silent at boot time
  • Adds udev support (mandatory for newest distributions to avoid remapping of devices in a different way as on the original system)
  • We also need vaft format support for USB boot
  • Adds libusual support (Ubuntu 7.10 needs it for USB)
  • Improve Ubuntu/Debian? keyboard detection and support
  • pbinit adapted to new pb (0.8.10). Filtering of docs done in it
  • Suppress some mondo warnings and errors on USB again
  • Tries to fix lack of files in deb mindi package
  • Verify should now work for USB devices
  • More log/mesages improvement for USB support
  • - Supress g_erase_tmpdir_and_scratchdir
  • Improve some log messages for USB support
  • Try to improve install in mindi to avoid issues with isolinux.cfg not installed vene if in the pkg :-(
  • Improve mindi-busybox build
  • In conformity with pb 0.8.9
  • Add support for Ubuntu 7.10 in build process
  • Add USB Key button to Menu UI (CD streamer removed)
  • Attempt to fix error messages on tmp/scratch files at the end by removing those dir at the latest possible.
  • Fix a bug linked to the size of the -E param which could be used (Arnaud Tiger/René? Ribaud).
  • Integrate ~/.pbrc content into mondorescue.pb (required project-builder >= 0.8.7)
  • Put mondorescue in conformity with new pb filtering rules
  • Add USB support at restore time (no test done yet). New start-usb script PB varibale added where useful
  • Unmounting USB device before removal of temporary scratchdir
  • Stil refining USB copy back to mondo (one command was not executed)
  • No need to have the image subdor in the csratchdir when USB.
  • umount the USB partition before attempting to use it
  • Remove useless copy from mindi to mondo at end of USB handling

(risky merge, we are raising the limits of 2 diverging branches. The status of stable is not completely sure as such. Will need lots of tests, but it's not yet done :-()
(merge -r1692:1769 $SVN_M/branches/2.2.5)

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