.TH DEBRAM 1 \
  "23 December 2006" "Debian Project" "Debian Ramification Manual"
.SH NAME
debram \- look \&.debs up in the Debian Ramification
.\"
.\" --------------------------------------------------------------------
.\"
.SH "SYNOPSIS"
.B debram
[
.B \-cwprtxABTXDMNP1lLu.sj?V
] [
.B \-d
.I package
]... [
.B \-m
.I maintainer
]... [
.IR ramification \&...
]
.\"
.\" --------------------------------------------------------------------
.\"
.SH "DESCRIPTION"
Debian GNU/Linux provides thousands upon daunting thousands of software
packages.  Sorting them into broad classes then dividing and redividing
them into finer, more specific branches, this command ramifies Debian's
packages in much the same manner as a university library ramifies its
books.  If you know what you want your computer to do but do not yet
know the package to do it, you can find the package here.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "QUICK START"
Give the command
.IP
.B debram \-cx
.PP
(Omit the
.RB \&` c \&'
option if your terminal has a white background or does not support
color.)  Now explore ram 1000 with
.IP
.B debram \-cx 1000
.PP
Observe the output, then retrieve a plan of ram 1100 with
.IP
.B debram \-cp 1100
.PP
Repeat the same operation with the abbreviation
.IP
.B debram \-cp 11
.PP
Again, but with cross-references.
.IP
.B debram \-cpx 11
.PP
Show the trunk above 1100.
.IP
.B debram \-cpt 11
.PP
Retrieve 1100's plan, showing also the trunk.
.IP
.B debram \-cptr 11
.PP
Enough plans.  Let's look at some packages.  Notice
.I 1112 File Listing and Finding
in the previous output, then
.IP
.B debram \-cx 1112
.PP
(Try adding a
.B \-w
option to the command if your terminal is at least 132 columns wide.)
Now list the same ram in brief.
.IP
.B debram \-cXD 1112
.PP
Again, and show the trunk this time.
.IP
.B debram \-cXDt 1112
.PP
Be very brief: list only the package names.
.IP
.B debram \-1 1112
.PP
Limit the listing to packages currently installed (or dpkg-selected).
.IP
.B dpkg --get-selections | debram \-cXDs 1112
.PP
What packages does E. Zini keep?
.IP
.B debram \-cm \&'E. Zini\&'
.PP
Suppose that you have been looking for the
.I tar
package, but have not seen it yet.  Find it now.
.IP
.B debram \-cd tar
.PP
Retrieve the entire Ramification plan.
.IP
.B debram \-cp | more \-f
.PP
Now you know enough to begin using the
.BR debram (1)
profitably.  If you have or can open a text terminal at least 132
columns wide, you will also wish to try the
.B \-w
option:
.IP
.B debram \-cxrw 3110 | less \-r
.PP
(Press \&`q' to exit
.BR less (1).)
To view the long, long listing of the entire ramification at once, enter
.IP
.B debram \-cxrw | less \-r
.PP
omitting the
.B \-w
if your terminal is only 80 columns wide.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "OPTIONS"
.SS Basic Output Formatting
.TP
.BR \-c , " --color"
Color-code the output (recommended).
.TP
.BR \-w , " --wide"
Output in 132-column format.  This is recommended if your terminal is
sufficiently wide.  (See below for a way to boot Linux into a 132x60
terminal.)
.SS Other General Options
.TP
.PD 0
.BI \-d package
.TP
.BI --find-deb= package
Find the named package.
.PD
.TP
.PD 0
.BI \-m maintainer
.TP
.BI --maint= maintainer
Find all
.IR maintainer \&'s
packages.
.PD
.TP
.BR \-p , " --plan"
Print the ramification plan or table of contents.  If a
.I ramification
is specified, print a partial plan descending from it.  (Implies
.BR \-r \&,
except when
.B \-t
is given.)
.TP
.BR \-r , " --recursive"
Print the entire tree under the given
.IR ramification \&.
.TP
.BR \-t , " --trunk" , " --recursive-up"
Print the trunk above the given
.IR ramification \&.
That is, print the ram, the parent ram, the grandparent ram, and so on,
up to the root of the tree.
.TP
.BR \-x , " --expand-xref"
Print cross-references in long-form, showing each ram's title rather
than just its number.
.SS Selective Output Suppression
The
.B \-A
and
.B \-B
options focus
.BR debram (1)'s
overall operation.  Usually
.BR debram (1)
prints the tables both of end-level ramifications (such as 1311 and
1312, each having a table of Debian packages) and of higher-level
ramifications (such as 1350 and 1300, each having only a table of
subramifications); but you may not always wish the two kinds of tables
intermixed, especially when requesting an
.B \-r
or
.B \-T
listing.
The
.B \-A
.RB ( --no-end-level )
and
.B \-B
.RB ( --only-end-level )
options respectively cause
.BR debram (1)
not to print the end-level and higher-level ramification tables.
.TP
.BR \-A , " --no-end-level"
Omit package tables.
.TP
.BR \-B , " --only-end-level"
Omit subramification tables.
.TP
.BR \-T , " --no-title"
Omit ramification titles.  (Implies
.BR \-X .)
.TP
.BR \-X , " --no-xref"
Omit cross-references.
.TP
.BR \-D , " --no-desc"
Omit package descriptions.
.TP
.BR \-M , " --no-maint"
Omit names of package maintainers.
.TP
.BR \-N , " --no-count"
Omit per-ramification \&.deb counts.
.TP
.BR \-P , " --no-pri"
Omit package priorities.
.TP
.BR \-1 , " --names-only"
Print package names only.  This option is equivalent to
.BR \-BTXDMNP \&.
.SS Manual Character-Encoding Selection
.BR debram (1)
defaults appropriately for your locale, so selecting a character
encoding manually is optional.  If your locale is the default
C/POSIX non-locale, then
.BR debram (1)
defaults to Latin-1\(emwhich is technically nonstandard behavior but for
.I debram
is usually the right thing to do.  Use
.B \-L
if you definitely want pure ascii.
.TP
.BR \-l , " --latin1"
Output and accept arguments in Latin-1 (iso-8859-1).
.TP
.BR \-L , " --ascii" , " --no-latin1"
Output and accept arguments in ascii.  (See also the
.B \-.
option.)
.TP
.BR \-u , " --utf8"
Output and accept arguments in utf-8 (Unicode) rather than Latin-1.
.SS Other Options
.TP
.BR \-\&. , " --ascii-dots"
In the output, fill blanks with ascii's \&`\&.\&' full-stop character
(rather than the middle dot, which ascii does not provide; see also the
.B \-L
option).
.TP
.BR \-s , " --selections"
Print only packages named on stdin.  The principal use of this option is
in
.RB \*(lq "dpkg --get-selections | debram \-s " "\&...\*(rq,"
which causes
.B debram
to ignore packages you have neither installed nor selected for
installation.  As such, the option accepts package names on standard
input, one name per line, each name optionally followed the word
\*(lqinstall\*(rq (which
.B debram
ignores).
.SS Seldom Used Options
.TP
.BR \-j , " --pri-one-color"
Output the package-priority column all in the same color: do not
differentiate.
.TP
.BI --data-file= file
Substitute clear-text
.I file
for the library data file.
.TP
.BI --data-file-gz= file
Substitute compressed
.I file
for the library data file.
.SS Metaoptions
.TP
.BR \-? , " --help"
Give a help list.
.TP
.B --usage
Give a short usage message.
.TP
.BR \-V , " --version"
Print the program version.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "RAMIFICATIONS"
A
.I ramification
is a branch of the Debian archive whose packages serve approximately the
same application domain or interest similar groups of users.  The first
division of the archive follows the traditional GNU/Linux manpage
hierarchy, with ram 1000 corresponding roughly to man section (1), ram
3000 to section (3), and so forth.  Further subramifications
successively focus on tighter domains.
.PP
.BR debram (1)
works on the
.I ramifications
you specify on the command line, defaulting to the umbrella
metaramification 0000 if you specify none.  The useful
.B \-r
.I recursive
option causes
.BR debram (1)
to select the named ramifications plus all subramifications branching
recursively from them.  Many rams cross-reference other rams across the
tree; by default the program concisely prints only cross-reference ram
numbers, but with the
.B \-x
option it prints expanded cross-reference information.
.PP
The branch-numbering system needs little explanation, except perhaps in
one respect: a ram number's count of non-zero digits always reveals its
ram's level.  Thus, for instance, 5060 and 5600 would each be
second-level rams under the top-level 5000, but 5660 would be a
third-level ram under the second-level 5600.
.PP
If you give fewer than four
.I ramification
digits,
.BR debram (1)
completes the number with zeros.  Thus
.B 8
is a valid abbreviation for
.BR 8000 \&,
for example.
.PP
Although the usage is not entirely consistent (even within this
manpage),
.IP \(bu
the top-level rams like 1000 and 8000 are usually called
.I sections
(after the traditional \*(lqman section\*(rq nomenclature),
.IP \(bu
the second-level rams like 1100 and 1200 are usually called
.IR divisions \&,
.IP \(bu
the third-level rams like 1110 and 1120 are usually called
.IR groups \&,
and
.IP \(bu
the end-level rams like 1121 and 1140 (the latter of which is an
end-level ram despite its number's ending in a zero) are usually called
.IR branches \&.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "UPDATING THE LIBRARY DATA"
As an autobiographer cannot cover the last events of his life, neither
can
.I debram
cover the last packages to enter Debian's stable release.
.I Debram
is fine as is, but if you prefer complete full coverage, then after the
release you can look for a revised
.IR debram-data
package bearing the same number as the version you now have (run
.RB \*(lq "debram \-V" \*(rq
for the number) but with a single letter appended.  For example, if you
now have version 1.2.3, then you can look for
.I debram-data
version 1.2.3a, 1.2.3b or the like.  Besides completing the coverage of
the stable release, such an update will undoubtedly also correct some
errors and oversights; so, it is worth getting if you want it.
.PP
The easiest place to get the update if you time it right will be from
Debian's unstable archive.  However, that archive must eventually drop
it in favor of a new development version, which is not what you want if
you are running Debian stable.  A more lasting source for the update
will be
.RS
.PP
.I http://sourceforge.net/projects/debram/
.RE
.PP
(Of course, no update can be guaranteed to appear\(emwhat is guaranteed
to appear is the
.I debram-data
you already have\(embut an update did appear for the last stable release
of Debian and is equally likely to appear for this one.  Look for it
within four to six months.)
.PP
If running Debian stable, you need not and probably should not update
the
.I debram
package itself; it suffices to update
.IR debram-data .
Furthermore, for Debian stable you should only update to the same
version with the single letter appended, as 1.2.3a.  Versions bearing
later numbers (like 1.2.4 or 1.3.0 against 1.2.3) are development
versions toward the following Debian release; they are probably not what
you want.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "WIDENING THE LINUX CONSOLE"
.BR debram (1)
was originally programmed to provide the most easily readable output
when invoked with the
.B \-cw
options on a 132-column wide terminal\(emespecially on the standard
.RB non- X (7)
Linux console (see
.BR console (4)).
Fewer users today use the console than used to, and
.BR X (7)
terminals typically show 132 columns or more in any case, so it's not as
important an issue as it used to be.  However, some console users may
still be interested to learn how to widen their consoles to the standard
wide-console width of 132 columns.  This section of the man page tells
how it can be done, at least on some computer hardware.
.PP
Exactly how to widen your Linux console depends on your specific
hardware and OS installation.  Nevertheless the following instructions
should lead you in the correct direction.
.RS
.PP
Print a hard copy of this manpage with
.IP
.B man \-Tps 1 debram | lpr
.PP
Reboot while holding <Shift> down (without the <Shift>, some Linux
machines are programmed never to offer you a boot prompt).  At the boot
prompt, enter
.IP
.B Linux video=vga16:off vga=ask
.PP
(Your kernel image may have some other name than \*(lqLinux\*(rq\&.
Also, the
.I video\&=
option may not be necessary for you.  Adapt your boot-prompt entry
accordingly.)
.PP
Notice that the kernel offers you the choice of several video modes.  If
you do not yet see 132x60,
.IR scan \&.
.PP
Choose
.IR 132x60 \&.
(The kernel may offer you hexadecimal numbers but demand decimal numbers
in return.  If you are reading this section of the manpage, you probably
already know how to convert hexadecimal to decimal, but if you feel
uncertain then refer to the table in
.BR ascii (7).)
.RE
.PP
If all is well the kernel now boots into a 132x60 console.
.PP
The foregoing procedure naturally gives you 132x60 only once: the kernel
returns to 80 columns the next time you boot it.  Configuring the kernel
to boot 132x60 by default requires editing
.I /etc/lilo.conf
then running
.BR lilo (8)
(presuming that you are booting with
.BR lilo (8);
else see
.B Grub
below).  The author has added the lines
.IP
vga=0x123
.br
append="video=vga16:off"
.PP
to the appropriate stanza of his own
.I /etc/lilo.conf
on at least one machine,
but yours may need something slightly different to achieve the desired
effect.  (The author got the number 0x123 for his video hardware during
the boot-time video-mode scan referenced above.  You can do likewise to
obtain the needed number for your video hardware.)
.PP
You may like the 132x60
.RB non- X (7)
Linux console.  The author does.  Try it if you wish.
.SS Grub
The foregoing assumes that you boot your Debian system with
.BR lilo (8).
A modern Debian system, however, is more likely booted with
.BR grub (8).
The author does not yet know the latter boot system well enough to write
a new man page section on it, but perhaps the present section provides
information even
.BR grub (8)
users will find of interest or use.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "FILES"
.PD 0
.TP
.I /usr/share/debram/debram.txt.gz
the default library data file (it is human-readable, too)
.TP
.I /usr/share/doc/debram/
reference documents including the
.I Command Selection Guide.
.PD
.\"
.\" --------------------------------------------------------------------
.\"
.SH "ENVIRONMENT"
.TP
.SM
.BR "LC_ALL" , " LC_CTYPE" , " LANG"
These variables optionally specify your locale, which determines how
.BR debram (1)
outputs non-ascii characters by default.  See
.BR locale (7)
for general information about locales.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "BUGS"
The
.B \-c
or
.B --color
option produces pleasing colors only on a terminal with a black
background, such as xterm and the standard non-X Linux console.
Other common terminals, such as the standard Gnome terminal, have white
backgrounds by default.  Users of these terminals probably will not find
the
.B \-c
option very useful.
.\" .PP
.\" (A technical bug:  Because the
.\" .B \-s
.\" option relies internally for speed's sake on <search.h>'s standard
.\" old hash interface, it can accept only a fixed maximum number of
.\" package names.  Presently the maximum is set at 32,768 which is two
.\" or three times
.\" .IR sarge \&'s
.\" size.  Not only does this mean that the
.\" .B \-s
.\" option fails to scale, but it also implies a momentarily but
.\" unnecessarily wasteful use of heap memory space when the
.\" .B \-s
.\" option is given with only a few package names.  The heap
.\" inefficiency arises only when the
.\" .B \-s
.\" option is given, however.)
.PP
Non-i386 architectures enjoy a handful of special packages not available
on i386.  Debram does not cover these.  Debram probably should at least
cover all the special amd64 packages, but it doesn't, yet.
.PP
Unavoidably in a ramification of this size, several packages
inadvertently yet undoubtedly remain misramified.  Report
misramifications sensibly, please, to Debian's Bug Tracking System.
If you are running Debian
.I stable,
please check the latest
.I debram-data
in Debian
.I unstable
before reporting the bug.
.\" .PP
.\" Visit
.\" .I http://debtags.alioth.debian.org
.\" for further information on
.\" .IR debtags \&/ debram
.\" development.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "AUTHOR"
Thaddeus H. Black <thb@debian.org>
.PP
Although the changelog details the direct parts several have played in
debram development, the author particularly wishes to acknowledge the
contributions of his Debian sponsor Giacomo Catenazzi, whose review and
counsel have made debram significantly better a package than it
otherwise would have been; and of the
.I debtags
development team led by Enrico Zini, who have welcomed the debram (they
might easily have done otherwise) and have gone out of their way to
integrate it successfully into the larger
.\" .I debtags
debtags
structure.
.\" .PP
.\" In a work of this size, some errors will inevitably be found despite
.\" the best advice.  Full responsibility for these naturally rests with
.\" the author.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "COPYLEFT"
Copyright (C) 2002\-2006 Thaddeus H. Black
.PP
.BR debram (1)
and all the files included in the
.I debram
package are free software; you can redistribute them and/or modify them
under the terms of the GNU General Public License, Version 2.
.\"
.\" --------------------------------------------------------------------
.\"
.SH "SEE ALSO"
.BR dpkg (8),
.BR apt-get (8),
.BR more (1),
.BR less (1),
the
.I Command Selection Guide
(included in the standard
.I debram
distribution),
.I debtags.deb