diff options
| -rw-r--r-- | Makefile.custom | 18 | ||||
| -rw-r--r-- | applets/Kbuild | 9 | ||||
| -rw-r--r-- | applets/applet_tables.c | 21 | ||||
| -rw-r--r-- | applets/usage.c | 14 | ||||
| -rw-r--r-- | applets/usage_pod.c | 97 | ||||
| -rwxr-xr-x | docs/autodocifier.pl | 307 | ||||
| -rw-r--r-- | docs/busybox_header.pod | 2 |
7 files changed, 132 insertions, 336 deletions
diff --git a/Makefile.custom b/Makefile.custom index d9a2367ab..b0ef05627 100644 --- a/Makefile.custom +++ b/Makefile.custom @@ -111,15 +111,19 @@ doc: docs/busybox.pod docs/BusyBox.txt docs/BusyBox.1 docs/BusyBox.html silent_cmd_doc = disp_doc = $($(quiet)cmd_doc) +# sed adds newlines after "Options:" etc, +# this is needed in order to get good BusyBox.{1,txt,html} docs/busybox.pod: $(srctree)/docs/busybox_header.pod \ $(srctree)/include/usage.h \ $(srctree)/docs/busybox_footer.pod \ - $(srctree)/docs/autodocifier.pl + applets/usage_pod $(disp_doc) $(Q)-mkdir -p docs - $(Q)-( cat $(srctree)/docs/busybox_header.pod ; \ - $(srctree)/docs/autodocifier.pl $(srctree)/include/usage.h ; \ - cat $(srctree)/docs/busybox_footer.pod ; ) > docs/busybox.pod + $(Q)-( \ + cat $(srctree)/docs/busybox_header.pod; \ + applets/usage_pod | sed 's/^[A-Za-z][A-Za-z ]*[a-z]:$$/&\n/'; \ + cat $(srctree)/docs/busybox_footer.pod; \ + ) > docs/busybox.pod docs/BusyBox.txt: docs/busybox.pod $(disp_doc) @@ -129,8 +133,7 @@ docs/BusyBox.txt: docs/busybox.pod docs/BusyBox.1: docs/busybox.pod $(disp_doc) $(Q)-mkdir -p docs - $(Q)-pod2man --center=BusyBox --release="version $(VERSION)" \ - $< > $@ + $(Q)-pod2man --center=BusyBox --release="version $(VERSION)" $< > $@ docs/BusyBox.html: docs/busybox.net/BusyBox.html $(disp_doc) @@ -140,8 +143,7 @@ docs/BusyBox.html: docs/busybox.net/BusyBox.html docs/busybox.net/BusyBox.html: docs/busybox.pod $(Q)-mkdir -p docs/busybox.net - $(Q)-pod2html --noindex $< > \ - docs/busybox.net/BusyBox.html + $(Q)-pod2html --noindex $< > $@ $(Q)-rm -f pod2htm* # documentation, cross-reference diff --git a/applets/Kbuild b/applets/Kbuild index 983037987..a966f6e5b 100644 --- a/applets/Kbuild +++ b/applets/Kbuild @@ -8,7 +8,7 @@ obj-y := obj-y += applets.o hostprogs-y:= -hostprogs-y += usage applet_tables +hostprogs-y += usage usage_pod applet_tables always:= $(hostprogs-y) @@ -22,13 +22,14 @@ else srctree_slash = $(srctree)/ endif - -HOSTCFLAGS_usage.o = -I$(srctree_slash)include +HOSTCFLAGS_usage.o = -I$(srctree_slash)include -Iinclude +HOSTCFLAGS_usage_pod.o = -I$(srctree_slash)include -Iinclude applets/applets.o: include/usage_compressed.h include/applet_tables.h -applets/usage: .config $(srctree_slash)applets/usage_compressed applets/applet_tables: .config +applets/usage: .config +applets/usage_pod: .config include/applet_tables.h quiet_cmd_gen_usage_compressed = GEN include/usage_compressed.h cmd_gen_usage_compressed = $(srctree_slash)applets/usage_compressed include/usage_compressed.h applets diff --git a/applets/applet_tables.c b/applets/applet_tables.c index 17135ddc1..e67f017e7 100644 --- a/applets/applet_tables.c +++ b/applets/applet_tables.c @@ -70,29 +70,32 @@ int main(int argc, char **argv) /* Keep in sync with include/busybox.h! */ - puts("/* This is a generated file, don't edit */\n"); + printf("/* This is a generated file, don't edit */\n\n"); printf("#define NUM_APPLETS %u\n", NUM_APPLETS); if (NUM_APPLETS == 1) { printf("#define SINGLE_APPLET_STR \"%s\"\n", applets[0].name); printf("#define SINGLE_APPLET_MAIN %s_main\n", applets[0].name); } + printf("\n"); - puts("\nconst char applet_names[] ALIGN1 = \"\""); + printf("const char applet_names[] ALIGN1 = \"\"\n"); for (i = 0; i < NUM_APPLETS; i++) { printf("\"%s\" \"\\0\"\n", applets[i].name); if (MAX_APPLET_NAME_LEN < strlen(applets[i].name)) MAX_APPLET_NAME_LEN = strlen(applets[i].name); } - puts(";"); + printf(";\n\n"); - puts("\nint (*const applet_main[])(int argc, char **argv) = {"); + printf("#ifndef SKIP_applet_main\n"); + printf("int (*const applet_main[])(int argc, char **argv) = {\n"); for (i = 0; i < NUM_APPLETS; i++) { printf("%s_main,\n", applets[i].main); } - puts("};"); + printf("};\n"); + printf("#endif\n\n"); - puts("const uint16_t applet_nameofs[] ALIGN2 = {"); + printf("const uint16_t applet_nameofs[] ALIGN2 = {\n"); for (i = 0; i < NUM_APPLETS; i++) { printf("0x%04x,\n", offset[i] @@ -105,10 +108,10 @@ int main(int argc, char **argv) #endif ); } - puts("};"); + printf("};\n\n"); #if ENABLE_FEATURE_INSTALLER - puts("const uint8_t applet_install_loc[] ALIGN1 = {"); + printf("const uint8_t applet_install_loc[] ALIGN1 = {\n"); i = 0; while (i < NUM_APPLETS) { int v = applets[i].install_loc; /* 3 bits */ @@ -117,7 +120,7 @@ int main(int argc, char **argv) printf("0x%02x,\n", v); i++; } - puts("};\n"); + printf("};\n\n"); #endif printf("#define MAX_APPLET_NAME_LEN %u\n", MAX_APPLET_NAME_LEN); diff --git a/applets/usage.c b/applets/usage.c index 1e038b367..d4fd12f9b 100644 --- a/applets/usage.c +++ b/applets/usage.c @@ -8,17 +8,17 @@ /* Just #include "autoconf.h" doesn't work for builds in separate * object directory */ -#include "../include/autoconf.h" +#include "autoconf.h" /* Since we can't use platform.h, have to do this again by hand: */ #if ENABLE_NOMMU -#define BB_MMU 0 -#define USE_FOR_NOMMU(...) __VA_ARGS__ -#define USE_FOR_MMU(...) +# define BB_MMU 0 +# define USE_FOR_NOMMU(...) __VA_ARGS__ +# define USE_FOR_MMU(...) #else -#define BB_MMU 1 -#define USE_FOR_NOMMU(...) -#define USE_FOR_MMU(...) __VA_ARGS__ +# define BB_MMU 1 +# define USE_FOR_NOMMU(...) +# define USE_FOR_MMU(...) __VA_ARGS__ #endif static const char usage_messages[] = "" diff --git a/applets/usage_pod.c b/applets/usage_pod.c new file mode 100644 index 000000000..058e0c842 --- /dev/null +++ b/applets/usage_pod.c @@ -0,0 +1,97 @@ +/* vi: set sw=4 ts=4: */ +/* + * Copyright (C) 2009 Denys Vlasenko. + * + * Licensed under GPLv2, see file LICENSE in this tarball for details. + */ +#include <unistd.h> +#include <stdint.h> +#include <string.h> +#include <stdio.h> + +/* Just #include "autoconf.h" doesn't work for builds in separate + * object directory */ +#include "autoconf.h" + +#define SKIP_applet_main +#define ALIGN1 /* nothing, just to placate applet_tables.h */ +#define ALIGN2 /* nothing, just to placate applet_tables.h */ +#include "applet_tables.h" + +/* Since we can't use platform.h, have to do this again by hand: */ +#if ENABLE_NOMMU +# define BB_MMU 0 +# define USE_FOR_NOMMU(...) __VA_ARGS__ +# define USE_FOR_MMU(...) +#else +# define BB_MMU 1 +# define USE_FOR_NOMMU(...) +# define USE_FOR_MMU(...) __VA_ARGS__ +#endif + +static const char usage_messages[] = "" +#define MAKE_USAGE +#include "usage.h" +#include "applets.h" +; + +int main(void) +{ + const char *names; + const char *usage; + int col, len2; + + col = 0; + names = applet_names; + while (*names) { + len2 = strlen(names) + 2; + if (col >= 76 - len2) { + printf(",\n"); + col = 0; + } + if (col == 0) { + col = 6; + printf("\t"); + } else { + printf(", "); + } + printf(names); + col += len2; + names += len2 - 1; + } + printf("\n\n"); + + printf("=head1 COMMAND DESCRIPTIONS\n\n"); + printf("=over 4\n\n"); + + names = applet_names; + usage = usage_messages; + while (*names && usage) { + if (*names >= 'a' && *names <= 'z' + && *usage != NOUSAGE_STR[0] + ) { + printf("=item B<%s>\n\n", names); + printf("%s %s\n\n", names, usage); + } + names += strlen(names) + 1; + usage += strlen(usage) + 1; + } + return 0; +} + +/* TODO: we used to make options bold with B<> and output an example too: + +=item B<cat> + +cat [B<-u>] [FILE]... + +Concatenate FILE(s) and print them to stdout + +Options: + -u Use unbuffered i/o (ignored) + +Example: + $ cat /proc/uptime + 110716.72 17.67 + +*/ diff --git a/docs/autodocifier.pl b/docs/autodocifier.pl deleted file mode 100755 index e3ba5c94b..000000000 --- a/docs/autodocifier.pl +++ /dev/null @@ -1,307 +0,0 @@ -#!/usr/bin/perl -w -# vi: set sw=4 ts=4: - -use strict; -use Getopt::Long; - -# collect lines continued with a '\' into an array -sub continuation { - my $fh = shift; - my @line; - - while (<$fh>) { - my $s = $_; - $s =~ s/\\\s*$//; - #$s =~ s/#.*$//; - push @line, $s; - last unless (/\\\s*$/); - } - return @line; -} - -# regex && eval away unwanted strings from documentation -sub beautify { - my $text = shift; - for (;;) { - my $text2 = $text; - $text =~ s/IF_NOT_\w+\(.*?"\s*\)//sxg; - $text =~ s/IF_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; - $text =~ s/USAGE_\w+\(\s*?(.*?)"\s*\)/$1"/sxg; - last if ( $text2 eq $text ); - } - $text =~ s/"\s*"//sg; - my @line = split("\n", $text); - $text = join('', - map { - s/^\s*"//; - s/"\s*$//; - s/%/%%/g; - s/\$/\\\$/g; - s/\@/\\\@/g; - eval qq[ sprintf(qq{$_}) ] - } @line - ); - return $text; -} - -# generate POD for an applet -sub pod_for_usage { - my $name = shift; - my $usage = shift; - - # Sigh. Fixup the known odd-name applets. -# Perhaps we can use some of APPLET_ODDNAME from include/applets.h ? - $name =~ s/dpkg_deb/dpkg-deb/g; - $name =~ s/fsck_minix/fsck.minix/g; - $name =~ s/mkfs_minix/mkfs.minix/g; - $name =~ s/run_parts/run-parts/g; - $name =~ s/start_stop_daemon/start-stop-daemon/g; - $name =~ s/ether_wake/ether-wake/g; - - # make options bold - my $trivial = $usage->{trivial}; - if (!defined $usage->{trivial}) { - $trivial = ""; - } else { - $trivial =~ s/(?<!\w)(-\w+)/B<$1>/sxg; - } - my @f0 = - map { $_ !~ /^\s/ && s/(?<!\w)(-\w+)/B<$1>/g; $_ } - split("\n", (defined $usage->{full} ? $usage->{full} : "")); - - # add "\n" prior to certain lines to make indented - # lines look right - my @f1; - my $len = @f0; - for (my $i = 0; $i < $len; $i++) { - push @f1, $f0[$i]; - if (($i+1) != $len && $f0[$i] !~ /^\s/ && $f0[$i+1] =~ /^\s/) { - next if ($f0[$i] =~ /^$/); - push(@f1, "") unless ($f0[$i+1] =~ /^\s*$/s); - } - } - my $full = join("\n", @f1); - - # prepare notes if they exist - my $notes = (defined $usage->{notes}) - ? "$usage->{notes}\n\n" - : ""; - - # prepare examples if they exist - my $example = (defined $usage->{example}) - ? - "Example:\n\n" . - join ("\n", - map { "\t$_" } - split("\n", $usage->{example})) . "\n\n" - : ""; - - # Pad the name so that the applet name gets a line - # by itself in BusyBox.txt - my $spaces = 10 - length($name); - if ($spaces > 0) { - $name .= " " x $spaces; - } - - return - "=item B<$name>". - "\n\n$name $trivial\n\n". - "$full\n\n" . - "$notes" . - "$example" . - "\n\n" - ; -} - -# the keys are applet names, and -# the values will contain hashrefs of the form: -# -# { -# trivial => "...", -# full => "...", -# notes => "...", -# example => "...", -# } -my %docs; - - -# get command-line options - -my %opt; - -GetOptions( - \%opt, - "help|h", - "pod|p", - "verbose|v", -); - -if (defined $opt{help}) { - print - "$0 [OPTION]... [FILE]...\n", - "\t--help\n", - "\t--pod\n", - "\t--verbose\n", - ; - exit 1; -} - - -# collect documenation into %docs - -foreach (@ARGV) { - open(USAGE, $_) || die("$0: $_: $!"); - my $fh = *USAGE; - my ($applet, $type, @line); - while (<$fh>) { - if (/^#define (\w+)_(\w+)_usage/) { - $applet = $1; - $type = $2; - @line = continuation($fh); - my $doc = $docs{$applet} ||= { }; - my $text = join("\n", @line); - $doc->{$type} = beautify($text); - } - } -} - - -# generate structured documentation - -my $generator = \&pod_for_usage; - -my @names = sort keys %docs; -my $line = "\t[, [[, "; -for (my $i = 0; $i < $#names; $i++) { - if (length ($line.$names[$i]) >= 65) { - print "$line\n\t"; - $line = ""; - } - $line .= "$names[$i], "; -} -print $line . $names[-1]; - -print "\n\n=head1 COMMAND DESCRIPTIONS\n"; -print "\n=over 4\n\n"; - -foreach my $applet (@names) { - print $generator->($applet, $docs{$applet}); -} - -exit 0; - -__END__ - -=head1 NAME - -autodocifier.pl - generate docs for busybox based on usage.h - -=head1 SYNOPSIS - -autodocifier.pl [OPTION]... [FILE]... - -Example: - - ( cat docs/busybox_header.pod; \ - docs/autodocifier.pl usage.h; \ - cat docs/busybox_footer.pod ) > docs/busybox.pod - -=head1 DESCRIPTION - -The purpose of this script is to automagically generate -documentation for busybox using its usage.h as the original source -for content. It used to be that same content has to be duplicated -in 3 places in slightly different formats -- F<usage.h>, -F<docs/busybox.pod>. This was tedious and error-prone, so it was -decided that F<usage.h> would contain all the text in a -machine-readable form, and scripts could be used to transform this -text into other forms if necessary. - -F<autodocifier.pl> is one such script. It is based on a script by -Erik Andersen <andersen@codepoet.org> which was in turn based on a -script by Mark Whitley <markw@codepoet.org> - -=head1 OPTIONS - -=over 4 - -=item B<--help> - -This displays the help message. - -=item B<--pod> - -Generate POD (this is the default) - -=item B<--verbose> - -Be verbose (not implemented) - -=back - -=head1 FORMAT - -The following is an example of some data this script might parse. - - #define length_trivial_usage \ - "STRING" - #define length_full_usage \ - "Prints out the length of the specified STRING." - #define length_example_usage \ - "$ length Hello\n" \ - "5\n" - -Each entry is a cpp macro that defines a string. The macros are -named systematically in the form: - - $name_$type_usage - -$name is the name of the applet. $type can be "trivial", "full", "notes", -or "example". Every documentation macro must end with "_usage". - -The definition of the types is as follows: - -=over 4 - -=item B<trivial> - -This should be a brief, one-line description of parameters that -the command expects. This will be displayed when B<-h> is issued to -a command. I<REQUIRED> - -=item B<full> - -This should contain descriptions of each option. This will also -be displayed along with the trivial help if CONFIG_FEATURE_TRIVIAL_HELP -is disabled. I<REQUIRED> - -=item B<notes> - -This is documentation that is intended to go in the POD or SGML, but -not be printed when a B<-h> is given to a command. To see an example -of notes being used, see init_notes_usage in F<usage.h>. I<OPTIONAL> - -=item B<example> - -This should be an example of how the command is actually used. -This will not be printed when a B<-h> is given to a command -- it -will only be included in the POD or SGML documentation. I<OPTIONAL> - -=back - -=head1 FILES - -F<usage.h> - -=head1 COPYRIGHT - -Copyright (c) 2001 John BEPPU. All rights reserved. This program is -free software; you can redistribute it and/or modify it under the same -terms as Perl itself. - -=head1 AUTHOR - -John BEPPU <b@ax9.org> - -=cut - diff --git a/docs/busybox_header.pod b/docs/busybox_header.pod index 9f2ffc48d..2a99636b1 100644 --- a/docs/busybox_header.pod +++ b/docs/busybox_header.pod @@ -8,7 +8,7 @@ BusyBox - The Swiss Army Knife of Embedded Linux busybox <applet> [arguments...] # or - <applet> [arguments...] # if symlinked + <applet> [arguments...] # if symlinked =head1 DESCRIPTION |