Contents of /magpie/README

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.
1	README for Magic 0.1:
2
3	WARNING: THIS IS THE FIRST PUBLIC RELEASE. YOU HAVE BEEN WARNED.
4
5	This program generates an extensively cross-referenced list of Debian
6	packages. It was motivated by my annoyance at the difficulty of
7	locating "interesting" Debian packages.
8
9	The software can generate output in several formats. The preferred
10	formats are docbook and debiandoc, but the resulting files are far
11	too complex for most systems to handle.
12
13
14	The software generates several types of output:
15
16	- Individual pages containing all known information about each package,
17	including the installation status of all referenced packages and
18	reverse listings for "depends" ("required by"), "suggests" ("suggested
19	by") and "recommends" ("recommended by").
20
21	- Overview pages containing the description of selected packages,
22	grouped by either subsection or priority
23
24	- Overview pages containing the description of all 'tasks',
25
26	- Overview pages containing the description of all installed programs,
27
28	- Index pages containing the summary of all packages, ordered by
29	package name, package source, or maintainer.
30
31	This program can require a lot of disk space - if you are indexing
32	Debian 2.2 you should have at least 30 MB free under /var/cache, although
33	only 8 MB is eventually used since the files are compressed.
34
35	This program also requires several minutes to run on a P-II 300.
36
37
38	Current Status:
39
40	- debiandoc
41
42	"debiandoc" is a standard SGML documentation on Debian systems.
43	It is the best choice on Debian systems, but can't be assumed
44	to exist on other platforms.
45
46	A simple enumeration of package details works. One neat trick
47	is to generate all package information as a standalone document
48	(not current done because of limited SUBDOC support) and then
49	run "debiandoc2man" on it. Use "section 10" for package information?
50
51	Problems: any type of indexing causes an "out-of-memory" error
52	on my system (with 256MB real memory!) It might be possible to
53	work around this by changing the SGML code (or interpreter!).
54
55	- docbook
56
57	"docbook" is a standard XML documentation format used by several
58	Open Source projects.
59
60	(Still preliminary implementation)
61
62	- texinfo
63
64	"texinfo" is an older metaformat which can produce TeX, GNU Info
65	or HTML documents.
66
67	A simple enumeration of package details works, and is searchable
68	via standard 'info' links. Can also generate PS and PDF list
69	of packages. A enumeration of all packages exceeds a magic
70	threshold in the TeX processor, but that should be a simple
71	configuration change.
72
73	Sadly, the document model doesn't really support what we need
74	to do. This mode is probably most useful in generating texinfo
75	material for each package.
76
77
78	- html
79
80	"html" is the simplest format we support.
81
82	- xml
83
84	The "XML" target contains only data. A separate XSL file and
85	appropriate browser is required to view the material.