Brief architectural notes about magpie for potential module writers:

Magpie runs in three major passes:

1) read the apt(8) and dpkg(8) databases.  This uses a yacc/lex parser,
   and is handled by database.c, parser.y and scanner.l and the
   keyword lists tag.g and tokens.g.

2) generate the reference stacks - everything under "details".
   This is handled by mod_core.o.

3) call each of modules to generate the indexes and miscellaneous
   reports.


Each module has four possible entry points:

1) init - perform additional system scans, if appropriate.  Generate
   any second-tier indexes.

2) annotated - generate annotated indexes.  The module is expected
   to write a "section" to the passed file pointer, with the first
   tier of the index included as a list, provided the number of
   elements is not unreasonable.  This function is also passed a
   flag indicating if indexes are desired for all packages or only
   installed packages.

3) unannotated - generate unannotated indexes.  The module is expected
   to write an "item" to the passed file pointer.  Again, this function
   is passed a flag indicating if indexes are desired for all packages
   or only installed packages.

4) miscellaneous - generate miscellaneous indexes and reports.  The
   module is expected to write an "item" to the passed file pointer.
   The URLs should clearly indicate if the index/report applies to
   all packages, installed packages, or a different categorization.
   

All output, except for unformatted text, should go through the
"emission" abstraction level.  At the current time "emit_X" will
always generate HTML output, but the module writer is cautioned
against assuming this will always be the case.

All multi-level indexes are strongly encouraged to include a
component count.

All annotated indexes should present data (at the lowest level)
as groups of ordered records.  Each group should be #named, and
that #name used as the target in the penultimate level.  This
rule can be broken when no grouping makes sense.  (E.g., in the
"tasks" list.)

All unannotated indexes should present all data in a single list.
This list may be nested.  (e.g., a list of maintainers, each of
whom has a list of packages.)

