[BusyBox] A small step toward auto-generating documentation...

Mark Whitley markw at lineo.com
Fri Feb 9 19:42:41 UTC 2001


Fellow Busyboxers,

Submitted for your approval is a wee bit o' Perl that extracts usage messages
from busybox usage.c and pretty-prints them to stdout. The Perl script and a
sample of the output it produces are attached.

The vision I have here is that this li'l script could live in the docs/
directory and be used to generate SGML documentation. Naturally, the output
would have to be massaged so as to produce SGML markup tags in all the right
places. Here's how I picture the auto-generation process working.

 1) Boilerplate "header" file gets copied to an output file.  (Basically,
	everything that is currently in busybox.sgml down to the "<title>BusyBox
	Commands</title>" line.)

 2) The xtr_usg.pl script runs and appends its output to the output file.

 3) Boilerplate "footer" file gets copied to the output file. (Basically,
	everything from the "<title>LIBC NSS</title>" line to eof.)


Benefits / Considerations:

 - Only have to document applets in one place: usage.c.

 - We will have to keep usage.c up-to-date and accurate. (I don't consider
   this a downside, just something we'll need to be more careful about.)

 - Any "general" info or special-case documentation (overview, credits, notest
   on testing, notes on libnss or pwd_grp) can go into the "header" or
   "footer" files.


Comments? Criticism? Lucrative movie offers?


Mark Whitley
markw at lineo.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xtr_usg.pl
Type: application/x-perl
Size: 793 bytes
Desc: not available
Url : http://lists.busybox.net/pipermail/busybox/attachments/20010209/cf7020a9/attachment.bin 
-------------- next part --------------

ar:
	ar -[ovR]{ptx} archive filenames
	Extract or list files from an ar archive.
	Options:
		-o		preserve original dates
		-p		extract to stdout
		-t		list
		-x		extract
		-v		verbosely list files processed
		-R		recursive action

basename:
	basename FILE [SUFFIX]
	Strips directory path and suffixes from FILE.
	If specified, also removes any trailing SUFFIX.

cat:
	cat [FILE]...
	Concatenates FILE(s) and prints them to stdout.

chgrp:
	chgrp [OPTION]... GROUP FILE...
	Change the group membership of each FILE to GROUP.
	Options:	-R	Changes files and directories recursively.

chmod:
	chmod [-R] MODE[,MODE]... FILE...
	Each MODE is one or more of the letters ugoa, one of the symbols +-= and
	one or more of the letters rwxst.
	Options:	-R	Changes files and directories recursively.

chown:
	chown [OPTION]...  OWNER[<.|:>[GROUP] FILE...
	Change the owner and/or group of each FILE to OWNER and/or GROUP.
	Options:	-R	Changes files and directories recursively.

chroot:
	chroot NEWROOT [COMMAND...]
	Run COMMAND with root directory set to NEWROOT.

chvt:
	chvt N
	Changes the foreground virtual terminal to /dev/ttyN

clear:
	clear
	Clear screen.


More information about the busybox mailing list