Document some of the new temporary files in generated/, add anchor tags.

1 files changed, 107 insertions, 76 deletions

diff --git a/www/code.html b/www/code.html
index 64ee98f..a5ffa15 100755
--- a/www/code.html
+++ b/www/code.html
@@ -129,7 +129,7 @@ files generated from other parts of the source code.</li>
 </ul>
 
 <a name="adding" />
-<p><h1>Adding a new command</h1></p>
+<p><h1><a href="#adding">Adding a new command</a></h1></p>
 <p>To add a new command to toybox, add a C file implementing that command under
 the toys directory.  No other files need to be modified; the build extracts
 all the information it needs (such as command line arguments) from specially
@@ -225,7 +225,7 @@ as appropriate by the time this function is called. (See
 <a href="#lib_args">get_optflags()</a> for details.</p></li>
 </ul>
 
-<a name="headers" /><h2>Headers.</h2>
+<a name="headers" /><h2><a href="#headers">Headers.</a></h2>
 
 <p>Commands generally don't have their own headers. If it's common code
 it can live in lib/, if it isn't put it in the command's .c file. (The line
@@ -252,7 +252,7 @@ that haven't changed since the 1990's, it's ok to #define them yourself or
 just use the constant inline with a comment explaining what it is. (A
 #define that's only used once isn't really helping.)</p>
 
-<p><a name="top" /><h2>Top level directory.</h2></p>
+<p><a name="top" /><h1><a href="#top">Top level directory.</a></h1></p>
 
 <p>This directory contains global infrastructure.</p>
 
@@ -460,13 +460,14 @@ install path prepended.</p></li>
 to build into toybox (thus generating a .config file), and by
 scripts/config2help.py to create generated/help.h.</p>
 
-<h3>Temporary files:</h3>
+<a name="generated" />
+<h1><a href="#generated">Temporary files:</a></h1>
 
 <p>There is one temporary file in the top level source directory:</p>
 <ul>
 <li><p><b>.config</b> - Configuration file generated by kconfig, indicating
 which commands (and options to commands) are currently enabled.  Used
-to make generated/config.h and determine which toys/*.c files to build.</p>
+to make generated/config.h and determine which toys/*/*.c files to build.</p>
 
 <p>You can create a human readable "miniconfig" version of this file using
 <a href=http://landley.net/aboriginal/new_platform.html#miniconfig>these
@@ -474,93 +475,121 @@ instructions</a>.</p>
 </li>
 </ul>
 
-<a name="generated" />
-<p>The "generated/" directory contains files generated from other source code
-in toybox.  All of these files can be recreated by the build system, although
-some (such as generated/help.h) are shipped in release versions to reduce
-environmental dependencies (I.E. so you don't need python on your build
-system).</p>
+<p><h2>Directory generated/</h2></p>
+
+<p>The remaining temporary files live in the "generated/" directory,
+which is for files generated at build time from other source files.</p>
 
 <ul>
+<li><p><b>generated/Config.in</b> - Included from the top level Config.in,
+contains one or more configuration entries for each command.</p>
+
+<p>Each command has a configuration entry with an upper case version of
+the command name. Options to commands start with the command
+name followed by an underscore and the option name. Global options are attached
+to the "toybox" command, and thus use the prefix "TOYBOX_".  This organization
+is used by scripts/cfg2files to select which toys/*/*.c files to compile for a
+given .config.</p>
+
+<p>A command with multiple names (or multiple similar commands implemented in
+the same .c file) should have config symbols prefixed with the name of their
+C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names
+have config symbols they must be options (symbols with an underscore and
+suffix) to the NEWTOY() name. (See generated/toylist.h)</p>
+</li>
+
 <li><p><b>generated/config.h</b> - list of CFG_SYMBOL and USE_SYMBOL() macros,
 generated from .config by a sed invocation in the top level Makefile.</p>
 
 <p>CFG_SYMBOL is a comple time constant set to 1 for enabled symbols and 0 for
-disabled symbols.  This allows the use of normal if() statements to remove
+disabled symbols. This allows the use of normal if() statements to remove
 code at compile time via the optimizer's dead code elimination (which removes
-from the binary any code that cannot be reached).  This saves space without
+from the binary any code that cannot be reached). This saves space without
 cluttering the code with #ifdefs or leading to configuration dependent build
-breaks.  (See the 1992 Usenix paper
+breaks. (See the 1992 Usenix paper
 <a href=http://doc.cat-v.org/henry_spencer/ifdef_considered_harmful.pdf>#ifdef
 Considered Harmful</a> for more information.)</p>
 
 <p>USE_SYMBOL(code) evaluates to the code in parentheses when the symbol
-is enabled, and nothing when the symbol is disabled.  This can be used
+is enabled, and nothing when the symbol is disabled. This can be used
 for things like varargs or variable declarations which can't always be
-eliminated by a simple test on CFG_SYMBOL.  Note that
+eliminated by a simple test on CFG_SYMBOL. Note that
 (unlike CFG_SYMBOL) this is really just a variant of #ifdef, and can
-still result in configuration dependent build breaks.  Use with caution.</p>
+still result in configuration dependent build breaks. Use with caution.</p>
 </li>
-</ul>
-
-<p><h2>Directory toys/</h2></p>
-
-<h3>toys/Config.in</h3>
-
-<p>Included from the top level Config.in, contains one or more
-configuration entries for each command.</p>
-
-<p>Each command has a configuration entry matching the command name (although
-configuration symbols are uppercase and command names are lower case).
-Options to commands start with the command name followed by an underscore and
-the option name.  Global options are attached to the "toybox" command,
-and thus use the prefix "TOYBOX_".  This organization is used by
-scripts/cfg2files to select which toys/*.c files to compile for a given
-.config.</p>
 
-<p>A command with multiple names (or multiple similar commands implemented in
-the same .c file) should have config symbols prefixed with the name of their
-C file.  I.E. config symbol prefixes are NEWTOY() names.  If OLDTOY() names
-have config symbols they're options (symbols with an underscore and suffix)
-to the NEWTOY() name.  (See toys/toylist.h)</p>
-
-<h3>toys/toylist.h</h3>
-<p>The first half of this file prototypes all the structures to hold
-global variables for each command, and puts them in toy_union.  These
-prototypes are only included if the macro NEWTOY isn't defined (in which
-case NEWTOY is defined to a default value that produces function
-prototypes).</p>
-
-<p>The second half of this file lists all the commands in alphabetical
-order, along with their command line arguments and install location.
-Each command has an appropriate configuration guard so only the commands that
-are enabled wind up in the list.</p>
-
-<p>The first time this header is #included, it defines structures and
-produces function prototypes for the commands in the toys directory.</p>
+<li><p><b>generated/flags.h</b> - FLAG_? macros indicating which command
+line options were seen. The option parsing in lib/args.c sets bits in
+toys.optflags, which can be tested by anding with the appropriate FLAG_
+macro. (Bare longopts, which have no corresponding short option, will
+have the longopt name after FLAG_. All others use the single letter short
+option.)</p>
+
+<p>To get the appropriate macros for your command, #define FOR_commandname
+before #including toys.h. To switch macro sets (because you have an OLDTOY()
+with different options in the same .c file), #define CLEANUP_oldcommand
+and also #define FOR_newcommand, then #include "generated/flags.h" to switch.
+</p>
+</li>
 
+<li><p><b>generated/globals.h</b> -
+Declares structures to hold the contents of each command's GLOBALS(),
+and combines them into "global_union this". (Yes, the name was
+chosen to piss off C++ developers who think that C
+is merely a subset of C++, not a language in its own right.)</p>
 
-<p>The first time it's included, it defines structures and produces function
-prototypes.
-  This
-is used to initialize toy_list in main.c, and later in that file to initialize
-NEED_OPTIONS (to figure out whether the command like parsing logic is needed),
-and to put the help entries in the right order in toys/help.c.</p>
+<p>The union reuses the same memory for each command's global struct:
+since only one command's globals are in use at any given time, collapsing
+them together saves space. The headers #define TT to the appropriate
+"this.commandname", so you can refer to the current command's global
+variables out of "this" as TT.variablename.</p>
 
-<h3>toys/help.h</h3>
+<p>The globals start zeroed, and the first few are filled out by the 
+lib/args.c argument parsing code called from main.c.</p>
+</li>
 
-<p>#defines two help text strings for each command: a single line
+<li><p><b>toys/help.h</b> -
+#defines two help text strings for each command: a single line
 command_help and an additinal command_help_long.  This is used by help_main()
 in toys/help.c to display help for commands.</p>
 
-<p>Although this file is generated from Config.in help entries by
-scripts/config2help.py, it's shipped in release tarballs so you don't need
-python on the build system.  (If you check code out of source control, or
-modify Config.in, then you'll need python installed to rebuild it.)</p>
+<p>This file is created by scripts/make.sh, which compiles scripts/config2help.c
+into the binary generated/config2help, and then runs it against the top
+level .config and Config.in files to extract the help text from each config
+entry and collate together dependent options.</p>
+
+<p>This file contains help text for all commands, regardless of current
+configuration, but only the ones currently enabled in the .config file
+wind up in the help_data[] array, and only the enabled dependent options
+have their help text added to the command they depend on.</p>
+</li>
 
-<p>This file contains help for all commands, regardless of current
-configuration, but only the currently enabled ones are entered into help_data[]
-in toys/help.c.</p>
+<li><p><b>generated/newtoys.h</b> - 
+All the NEWTOY() and OLDTOY() macros in alphabetical order,
+each of which should be inside the appropriate USE_ macro. (Ok, not _quite_
+alphabetical orer: the "toybox" multiplexer is always the first entry.)</p>
+
+<p>By #definining NEWTOY() to various things before #including this file,
+it may be used to create function prototypes (in toys.h), initialize the
+toy_list array (in main.c, the alphabetical order lets toy_find() do a
+binary search), initialize the help_data array (in lib/help.c), and so on.
+(It's even used to initialize the NEED_OPTIONS macro, which is has a 1 or 0
+for each command using command line option parsing, ORed together.
+This allows compile-time dead code elimination to remove the whole of
+lib/args.c if nothing currently enabled is using it.)<p>
+
+<p>Each NEWTOY and OLDTOY macro contains the command name, command line
+option string (telling lib/args.c how to parse command line options for
+this command), recommended install location, and miscelaneous data such
+as whether this command should retain root permissions if installed suid.</p>
+</li>
+
+<li><p><b>toys/oldtoys.h</b> - Macros with the command line option parsing
+string for each NEWTOY. This allows an OLDTOY that's just an alias for an
+existing command to refer to the existing option string instead of
+having to repeat it.</p>
+</li>
+</ul>
 
 <a name="lib">
 <h2>Directory lib/</h2>
@@ -648,14 +677,16 @@ struct double_list *new) - append existing struct double_list to
 list, does not allocate anything.</p></li></ul>
 </ul>
 
-<b>Trivia questions:</b>
+<b>List code trivia questions:</b>
 
 <ul>
 <li><p><b>Why do arg_list and double_list contain a char * payload instead of
 a void *?</b> - Because you always have to typecast a void * to use it, and
-typecasting a char * does no harm. Thus having it default to the most common
-pointer type saves a few typecasts (strings are the most common payload),
-and doesn't hurt anything otherwise.</p>
+typecasting a char * does no harm. Since strings are the most common
+payload, and doing math on the pointer ala
+"(type *)(ptr+sizeof(thing)+sizeof(otherthing))" requires ptr to be char *
+anyway (at least according to the C standard), defaulting to char * saves
+a typecast.</p>
 </li>
 
 <li><p><b>Why do the names ->str, ->arg, and ->data differ?</b> - To force
@@ -664,10 +695,10 @@ be bad, and _failing_ to free(node->arg) leaks memory.</p></li>
 
 <li><p><b>Why does llist_pop() take a void * instead of void **?</b> -
 because the stupid compiler complains about "type punned pointers" when
-you typecast and dereference ont he same line,
+you typecast and dereference on the same line,
 due to insane FSF developers hardwiring limitations of their optimizer
 into gcc's warning system. Since C automatically typecasts any other
-pointer _down_ to a void *, the current code works fine. It's sad that it
+pointer type to and from void *, the current code works fine. It's sad that it
 won't warn you if you forget the &, but the code crashes pretty quickly in
 that case.</p></li>
 
@@ -1077,8 +1108,8 @@ from elsewhere in the program. This gives ls -lR manual control
 of traversal order, which is neither depth first nor breadth first but
 instead a sort of FIFO order requried by the ls standard.</p>
 
-<a name="#toys">
-<h2>Directory toys/</h2>
+<a name="toys">
+<h1><a href="#toys">Directory toys/</a></h1>
 
 <p>This directory contains command implementations. Each command is a single
 self-contained file. Adding a new command involves adding a single