README for Magic 0.1:

WARNING: THIS IS THE FIRST PUBLIC RELEASE.  YOU HAVE BEEN WARNED.

This program generates an extensively cross-referenced list of Debian
packages.  It was motivated by my annoyance at the difficulty of
locating "interesting" Debian packages.

The software can generate output in several formats.  The preferred
formats are docbook and debiandoc, but the resulting files are far
too complex for most systems to handle.


The software generates several types of output:

 - Individual pages containing all known information about each package,
   including the installation status of all referenced packages and
   reverse listings for "depends" ("required by"), "suggests" ("suggested
   by") and "recommends" ("recommended by").

 - Overview pages containing the description of selected packages,
   grouped by either subsection or priority

 - Overview pages containing the description of all 'tasks',

 - Overview pages containing the description of all installed programs,

 - Index pages containing the summary of all packages, ordered by
   package name, package source, or maintainer.

This program can require a *lot* of disk space - if you are indexing
Debian 2.2 you should have at least 30 MB free under /var/cache, although 
only 8 MB is eventually used since the files are compressed.

This program also requires several minutes to run on a P-II 300.


Current Status:

 - debiandoc

   "debiandoc" is a standard SGML documentation on Debian systems.
   It is the best choice on Debian systems, but can't be assumed
   to exist on other platforms.

   A simple enumeration of package details works.  One neat trick 
   is to generate all package information as a standalone document
   (not current done because of limited SUBDOC support) and then
   run "debiandoc2man" on it.  Use "section 10" for package information?

   Problems: any type of indexing causes an "out-of-memory" error 
   on my system (with 256MB real memory!)  It might be possible to
   work around this by changing the SGML code (or interpreter!).

 - docbook

   "docbook" is a standard XML documentation format used by several
   Open Source projects.  

   (Still preliminary implementation)

 - texinfo

   "texinfo" is an older metaformat which can produce TeX, GNU Info
   or HTML documents.

   A simple enumeration of package details works, and is searchable
   via standard 'info' links.  Can also generate PS and PDF list
   of packages.  A enumeration of *all* packages exceeds a magic
   threshold in the TeX processor, but that should be a simple 
   configuration change.

   Sadly, the document model doesn't really support what we need 
   to do.  This mode is probably most useful in generating texinfo
   material for each package.


 - html

   "html" is the simplest format we support.

 - xml

   The "XML" target contains only data.  A separate XSL file and
   appropriate browser is required to view the material.
