The function hierarchy in the data-generation programs (bin/mk_*) is a bit
complex. In general, the top-level functions call common functions to handle
parameters, passing a reference to a function that actually generates the data.


CGI

do_cgi() --> cgi_handle_params() --> cgi_mk_graph() --> mk_graph() --> ...

1. Each CGI program has a do_cgi() function that gathers parameter info and
   calls cgi_handle_params(), specifying a function for generating the data.

2. cgi_handle_params() is a common function that parses and checks CGI
   parameters and then calls the specified function.

3. Each CGI program has a function, such as cgi_mk_graph(), that may do
   additional parameter checking. The function then prints a CGI header,
   runs the appropriate data generation function, and prints the output.

4. The data generation function is not CGI-specific, so from here downward
   the function path is the same as for CLI.


CLI

do_write() --> arg_handle_params() --> arg_mk_graph() -->
    write_output_to_file() --> mk_graph() --> ...

1. Each CLI program has a do_write() function that gathers parameter info and
   calls arg_handle_params(), specifying a function for generating the data and
   a file to which the data will be written.

2. arg_handle_params() is a common function that parses and checks the
   parameters argument and then calls the specified function, passing the file
   name onward.

3. Each CLI program has a function, such as arg_mk_graph(), that may do
   additional parameter checking. The function then calls
   write_output_to_file(), specifying a function for generating the data.

4. write_output_to_file() is a common function that opens a file, runs the
   specified data-generation function, and writes the output to the file.

5. The data generation function is not CLI-specific, so from here downward
   the function path is the same as for CGI.


RECURSIVE CLI

do_recur() --> arg_handle_params() --> arg_mk_mainpage() -->
    write_output_to_file() -> mk_mainpage() --> ... --> mk_link() --> tree_put() -->
    recur_next() --> write_output_to_file() --> ...etc...

This starts out the same as the regular CLI function order, except that
do_recur() takes the place of do_write(). do_recur() sets $common->{recur} to a
non-undef value and calls arg_handle_params() as usual.

If the program ever calls mk_link() to refer to another Captrap file, mk_link()
will see $common->{recur} and call the recursive functions, which keep track of
what has been written already, decide a new file name, and call
write_output_to_file() (and so on).


EOF