magpie/magpie/magpie.8

.TH MAGPIE 8 
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.SH NAME
magpie \- Debian reference librarian
.SH SYNOPSIS
.B magpie
.SH "DESCRIPTION"
.BR Magpie
is a reference librarian for Debian systems which should be run
overnight by
.BR
cron (8).
It reads the 
.BR apt (8)
and
.BR dpkg (8)
databases and can perform additional tasks specified by dynamically
loaded modules.  It then generates a number of web pages that 
should make it easy to answer questions such as:
.IP
"I've been hearing a lot about MP3 and XML lately.  What packages
should I consider loading?"
.IP
"Help!  I'm running out of disk space!  What packages will give me
the most "bang for the buck" if I purge them?  What other packages
will I have to delete at the same time?"
.IP
"I see that a new 'foobar' package is available.  Before I upgrade,
did I make any local changes that I need to preserve?"
.IP
"What suid programs are \fBnot\fR associated with a package?"

.PP
.BR Magpie
first creates extensively cross-referenced reports under
.BR /var/cache/magpie.
These "reference stacks" provide an individual document with the
following details about every package:
.IP 
Name
.br
Descriptive summary
.br
Description
.br
Version
.br
Section and category
.br
Priority
.br
Filename
.br
Maintainer (cross-linked)
.br
Pre-dependency list (cross-referenced)
.br
Dependency list (cross-referenced)
.br
Reverse dependency list (cross-referenced)
.br
Suggestion list (cross-referenced)
.br
Reverse suggestion list (cross-referenced)
.br
Recommendation list (cross-referenced)
.br
Reverse recommendation list (cross-referenced)
.br
MD5 checksum
.br
Package size
.br
Known bugs (link to http://bugs.debian.org)

.PP
If the package is installed, these documents contain several
aditional fields:
.IP
Installation status
.br
Installed size
.br
Conffiles
.br
Results of running
.BR md5sum (1)
against package's md5sums list.

.PP
.BR Magpie
always writes the package lists in tabular format.  Packages are normally
listed one to a line, but acceptable alternatives are grouped.  Each
line includes the package name, restrictions (if any), summary, and
the installed version (if known).

.PP
.BR Magpie
then writes several annotated indexes containing the package name,
version, installation status, and description (not summary).  The
indexes include:
.IP "by section"
All packages are listed, grouped by section and category, then collated by name
within each priority.
.IP "by priority"
All packages are listed, grouped by priority and section, then collated by name
within each category.
.IP "by task"
All "task" packages are listed.
.IP "installed packages"
All installed packages are listed, collated by name within each category.

.PP
.BR Magpie
then writes several unannotated indexes containing the package name,
installation status and descriptive summary.  The indexes include:
.IP "by name"
All packages are listed, collated by name.
.IP "by maintainer"
All packages are listed, grouped by maintainer, then collated by name.
.IP "by source"
All packages are listed, grouped by source package then collated by name.
.IP "by size"
All packages are listed, sorted by decreasing package size.
.IP "by MD5 checksum"
All packages are listed, sorted by md5sum.  Even reference librarians
need to cut loose sometimes.

.PP
.BR Magpie
then writes a number of "keyword in context (KWIC)" indexes.  Due to
popular demand, to say nothing of the sheer size of a complete KWIC
index, these indexes are now annotated indexes tagged by keywords.

.PP
.BR Magpie
concludes by writing several special reports.  The reports include:
.IP "conffiles"
All registered "conffiles"
.IP "checksums"
All packages containing files whose MD5 checksums do not match the
declared value.  (N.B., this is not a replacement for tripwire!)
.IP "setuid files"
All files with the "setuid" bit set, cross-referenced to the package
which contains them (if identifiable).

.PP
.BR Magpie
can load modules at run-time, so this list may not be exhaustive.

.PP
Finally, a "magpie" is a medium sized bird in the American West
which is well known for collecting shiny bits of trash for its
nest.

.SH "SEE ALSO"
.BR apt-cache (8),
.BR dpkg (8),
.BR cron (8),
.BR tripwire (8)
.SH BUGS
.BR Magpie
does not yet allow specification of target directory or username
from command line.
.PP
.BR Magpie
does not yet support dynamically loaded modules.
.PP
.BR Magpie 
does not lock the
.BR apt (8)
or
.BR dpkg (8)
files.
.PP
.BR Magpie 
generates a surprising amount of data.  Since most of the
output will never be viewed, the program compresses the output.  You
should still have approx. 30 MB available for the Debian 2.2 packages.
.PP
.BR Magpie
uses a parser constructed by
.BR bison (1)
and
.BR flex (1).
The parser is very fast, but very easily confused by unexpected 
values.  Known problems include the new non-US format, old 
.BR dpkg (8)
data, and unofficial packages with strange section information.
The problem can usually be fixed by editing the database.
.PP
The detailed pages can be hard to read under
.BR lynx (1)
due to the extensive use of tables.
I have not tested the pages under 
.BR MSIE (6).
.SH AUTHOR
This manual page was written by Bear Giles <bgiles@coyotesong.com>.
1	.TH MAGPIE 8
2	.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
3	.\" other parms are allowed: see man(7), man(1)
4	.SH NAME
5	magpie \- Debian reference librarian
6	.SH SYNOPSIS
7	.B magpie
8	.SH "DESCRIPTION"
9	.BR Magpie
10	is a reference librarian for Debian systems which should be run
11	overnight by
12	.BR
13	cron (8).
14	It reads the
15	.BR apt (8)
16	and
17	.BR dpkg (8)
18	databases and can perform additional tasks specified by dynamically
19	loaded modules. It then generates a number of web pages that
20	should make it easy to answer questions such as:
21	.IP
22	"I've been hearing a lot about MP3 and XML lately. What packages
23	should I consider loading?"
24	.IP
25	"Help! I'm running out of disk space! What packages will give me
26	the most "bang for the buck" if I purge them? What other packages
27	will I have to delete at the same time?"
28	.IP
29	"I see that a new 'foobar' package is available. Before I upgrade,
30	did I make any local changes that I need to preserve?"
31	.IP
32	"What suid programs are \fBnot\fR associated with a package?"
33
34	.PP
35	.BR Magpie
36	first creates extensively cross-referenced reports under
37	.BR /var/cache/magpie.
38	These "reference stacks" provide an individual document with the
39	following details about every package:
40	.IP
41	Name
42	.br
43	Descriptive summary
44	.br
45	Description
46	.br
47	Version
48	.br
49	Section and category
50	.br
51	Priority
52	.br
53	Filename
54	.br
55	Maintainer (cross-linked)
56	.br
57	Pre-dependency list (cross-referenced)
58	.br
59	Dependency list (cross-referenced)
60	.br
61	Reverse dependency list (cross-referenced)
62	.br
63	Suggestion list (cross-referenced)
64	.br
65	Reverse suggestion list (cross-referenced)
66	.br
67	Recommendation list (cross-referenced)
68	.br
69	Reverse recommendation list (cross-referenced)
70	.br
71	MD5 checksum
72	.br
73	Package size
74	.br
75	Known bugs (link to http://bugs.debian.org)
76
77	.PP
78	If the package is installed, these documents contain several
79	aditional fields:
80	.IP
81	Installation status
82	.br
83	Installed size
84	.br
85	Conffiles
86	.br
87	Results of running
88	.BR md5sum (1)
89	against package's md5sums list.
90
91	.PP
92	.BR Magpie
93	always writes the package lists in tabular format. Packages are normally
94	listed one to a line, but acceptable alternatives are grouped. Each
95	line includes the package name, restrictions (if any), summary, and
96	the installed version (if known).
97
98	.PP
99	.BR Magpie
100	then writes several annotated indexes containing the package name,
101	version, installation status, and description (not summary). The
102	indexes include:
103	.IP "by section"
104	All packages are listed, grouped by section and category, then collated by name
105	within each priority.
106	.IP "by priority"
107	All packages are listed, grouped by priority and section, then collated by name
108	within each category.
109	.IP "by task"
110	All "task" packages are listed.
111	.IP "installed packages"
112	All installed packages are listed, collated by name within each category.
113
114	.PP
115	.BR Magpie
116	then writes several unannotated indexes containing the package name,
117	installation status and descriptive summary. The indexes include:
118	.IP "by name"
119	All packages are listed, collated by name.
120	.IP "by maintainer"
121	All packages are listed, grouped by maintainer, then collated by name.
122	.IP "by source"
123	All packages are listed, grouped by source package then collated by name.
124	.IP "by size"
125	All packages are listed, sorted by decreasing package size.
126	.IP "by MD5 checksum"
127	All packages are listed, sorted by md5sum. Even reference librarians
128	need to cut loose sometimes.
129
130	.PP
131	.BR Magpie
132	then writes a number of "keyword in context (KWIC)" indexes. Due to
133	popular demand, to say nothing of the sheer size of a complete KWIC
134	index, these indexes are now annotated indexes tagged by keywords.
135
136	.PP
137	.BR Magpie
138	concludes by writing several special reports. The reports include:
139	.IP "conffiles"
140	All registered "conffiles"
141	.IP "checksums"
142	All packages containing files whose MD5 checksums do not match the
143	declared value. (N.B., this is not a replacement for tripwire!)
144	.IP "setuid files"
145	All files with the "setuid" bit set, cross-referenced to the package
146	which contains them (if identifiable).
147
148	.PP
149	.BR Magpie
150	can load modules at run-time, so this list may not be exhaustive.
151
152	.PP
153	Finally, a "magpie" is a medium sized bird in the American West
154	which is well known for collecting shiny bits of trash for its
155	nest.
156
157	.SH "SEE ALSO"
158	.BR apt-cache (8),
159	.BR dpkg (8),
160	.BR cron (8),
161	.BR tripwire (8)
162	.SH BUGS
163	.BR Magpie
164	does not yet allow specification of target directory or username
165	from command line.
166	.PP
167	.BR Magpie
168	does not yet support dynamically loaded modules.
169	.PP
170	.BR Magpie
171	does not lock the
172	.BR apt (8)
173	or
174	.BR dpkg (8)
175	files.
176	.PP
177	.BR Magpie
178	generates a surprising amount of data. Since most of the
179	output will never be viewed, the program compresses the output. You
180	should still have approx. 30 MB available for the Debian 2.2 packages.
181	.PP
182	.BR Magpie
183	uses a parser constructed by
184	.BR bison (1)
185	and
186	.BR flex (1).
187	The parser is very fast, but very easily confused by unexpected
188	values. Known problems include the new non-US format, old
189	.BR dpkg (8)
190	data, and unofficial packages with strange section information.
191	The problem can usually be fixed by editing the database.
192	.PP
193	The detailed pages can be hard to read under
194	.BR lynx (1)
195	due to the extensive use of tables.
196	I have not tested the pages under
197	.BR MSIE (6).
198	.SH AUTHOR
199	This manual page was written by Bear Giles <bgiles@coyotesong.com>.