some doc updates
Hi,
Two patches for dpkg(8), both in nroff and in SGML. Random stuff I've
accumulated over the years but never bothered to send over :) The recent
cvs update created a lot of conflicts here so I've had to fix it, and I
decided to send it over.
The small patch is for the dpkg-dev description.
--
2. That which causes joy or happiness.
Index: debian/control
===================================================================
RCS file: /cvs/dpkg/dpkg/debian/control,v
retrieving revision 1.35
diff -u -r1.35 control
--- debian/control 2002/05/26 03:53:43 1.35
+++ debian/control 2002/06/21 23:04:46
@@ -58,11 +58,13 @@
Conflicts: dpkgname
Replaces: dpkgname, dpkg (<< 1.4.1.8), dpkg-doc-ja
Description: Package building tools for Debian
- This package contains the tools (including dpkg-source) required to
- unpack, build and upload Debian source packages.
+ This package contains the necessary tools required to unpack
+ (dpkg-source), build (dpkg-buildpackage, dpkg-architecture,
+ dpkg-gencontrol, dpkg-shlibdeps) and prepare Debian source packages
+ for upload (dpkg-distaddfile, dpkg-genchanges, dpkg-parsechangelog).
.
- Most Debian source packages will require additional tools to build -
- for example, most packages need the `make' and the C compiler `gcc'.
+ Also included are the basic .deb package format documentation and
+ utilities for building Packages and Sources files.
Package: dpkg-doc
Section: doc
Index: main/dpkg.8
===================================================================
RCS file: /cvs/dpkg/dpkg/main/dpkg.8,v
retrieving revision 1.32
diff -u -r1.32 dpkg.8
--- main/dpkg.8 2002/05/26 03:53:43 1.32
+++ main/dpkg.8 2002/06/21 23:04:46
@@ -1,33 +1,31 @@
-.TH DPKG 8 "April 12, 1998" "Debian Project" "dpkg suite"
+.TH DPKG 8 "February 2000" "Debian Project" "dpkg suite"
.SH NAME
-dpkg \- a medium-level package manager for Debian
-
+dpkg \- medium-level package manager for Debian
+..
.SH SYNOPSIS
.B dpkg
[\fIoptions\fP] \fIaction\fP
-
+..
.SH WARNING
This manual is intended for users wishing to understand \fBdpkg\fP's
command line options and package states in more detail than that
provided by \fBdpkg --help\fP.
-
+.PP
It should \fInot\fP be used by package maintainers wishing to
understand how \fBdpkg\fP will install their packages. The
descriptions of what \fBdpkg\fP does when installing and removing
-packages are particularly inadequate. For detailed information about
-this, please refer to the \fIPackage Management System\fP topic under
-\fIdebian-faq\fP in the GNU Info system. For information about
-creating Debian packages, see the \fIDebian Package Management
-Tools\fP topic in the same place.
-
+packages are particularly inadequate.
+.PP
+For information about this, please refer to sections regarding the
+Debian packaging system in the Debian FAQ or the Debian Reference.
+..
.SH DESCRIPTION
\fBdpkg\fP is a medium-level tool to install, build, remove and manage
-Debian packages. The primary and more user-friendly
-front-end for \fBdpkg\fP is \fBdselect\fP(8). \fBdpkg\fP itself is
+Debian packages. \fBdpkg\fP is
controlled entirely via command line parameters, which consist of exactly
one action and zero or more options. The action-parameter tells dpkg
what to do and options control the behavior of the action in some way.
-
+.PP
\fBdpkg\fP can be also be used as a front-end to \fBdpkg-deb\fP.
The following
are \fBdpkg-deb\fP actions, and if they are encountered, \fBdpkg\fP
@@ -43,7 +41,11 @@
\fB--fsys-tarfile\fP.
.fi
Please refer to \fBdpkg-deb\fP(1) for information about these actions.
-
+.PP
+Note: the primary and more user-friendly front-end for \fBdpkg\fP is
+\fBdselect\fP(8). There are other front-ends such as those based on
+\fBapt\fP(8).
+..
.SH INFORMATION ABOUT PACKAGES
\fBdpkg\fP maintains some usable information about available
packages. The information is divided in three classes: \fBstates\fP,
@@ -92,37 +94,31 @@
A package marked \fBreinst-required\fP is broken and requires
reinstallation. These packages cannot be removed, unless forced with
option \fB--force-reinstreq\fP.
-
+..
.SH ACTIONS
.TP
\fBdpkg -i\fP | \fB--install\fP \fIpackage_file\fP...
Install the package. If \fB--recursive\fP or \fB-R\fP option is
specified, \fIpackage_file\fP must refer to a directory instead.
-
+.PP
Installation consists of the following steps:
.br
-
\fB1.\fP Extract the control files of the new package.
.br
-
\fB2.\fP If another version of the same package was installed before
the new installation, execute \fIprerm\fP script of the old package.
.br
-
\fB3.\fP Run \fIpreinst\fP script, if provided by the package.
.br
-
\fB4.\fP Unpack the new files, and at the same time back up the old
files, so that if something goes wrong, they can be restored.
.br
-
\fB5.\fP If another version of the same package was installed before
the new installation, execute the \fIpostrm\fP script of the old
package. Note that this script is executed after the \fIpreinst\fP
script of the new package, because new files are written at the same
time old files are removed.
.br
-
\fB6.\fP Configure the package. See \fB--configure\fP for detailed
information about how this is done.
.TP
@@ -135,15 +131,13 @@
Reconfigure an unpacked package. If \fB-a\fP or \fB--pending\fP is
given instead of \fIpackage\fP, all unpacked but unconfigured
packages are configured.
-
+.PP
Configuring consists of the following steps:
.br
-
\fB1.\fP Unpack the configuration files, and at the same time back up
the old configuration files, so that they can be restored if
something goes wrong.
.br
-
\fB2.\fP Run \fIpostinst\fP script, if provided by the package.
.TP
\fBdpkg -r\fP | \fB--remove\fP | \fB-P\fP | \fB--purge \fP\fIpackage\fP ... | \fB-a\fP | \fB--pending\fP
@@ -156,16 +150,13 @@
name, then all packages unpacked, but marked to be removed or purged
in file \fI/var/lib/dpkg/status\fP, are removed or purged,
respectively.
-
+.PP
Removing of a package consists of the following steps:
.br
-
\fB1.\fP Run \fIprerm\fP script
.br
-
\fB2.\fP Remove the installed files
.br
-
\fB3.\fP Run \fIpostrm\fP script
.br
.TP
@@ -256,7 +247,7 @@
are not reset for subsequent commands executed during the same run.
.TP
.B dpkg --help
-Display a brief help message.
+Display the usage instructions.
.TP
.B dpkg --force-help
Give help about the \fB--force-\fP\fIthing\fP options.
@@ -265,14 +256,14 @@
Give help about debugging options.
.TP
\fBdpkg --licence\fP | \fBdpkg --license\fP
-Display \fBdpkg\fP licence.
+Display \fBdpkg\fP copyright and licence information.
.TP
\fBdpkg --version\fP
Display \fBdpkg\fP version information.
.TP
\fBdpkg-deb-actions\fP
See \fBdpkg-deb\fP(1) for more information about the following actions.
-
+.PP
.nf
\fBdpkg -b\fP | \fB--build\fP \fIdirectory\fP [\fIfilename\fP]
Build a deb package.
@@ -293,7 +284,7 @@
Extract and display the filenames contained by a
package.
.fi
-
+..
.SH OPTIONS
All options can be specified both on the commandline and in the \fBdpkg\fP
configuration file \fI/etc/dpkg/dpkg.cfg\fP. Each line in the configuration
@@ -329,91 +320,90 @@
2000 Insane amounts of drivel
.TP
\fB--force-\fP\fIthings\fP | \fB--no-force-\fP\fIthings\fP | \fB--refuse-\fP\fIthings\fP
-
Force or refuse (\fBno-force\fP and \fBrefuse\fP mean the same thing)
to do some things. \fIthings\fP is a comma separated list of things
specified below. \fB--force-help\fP displays a message describing them.
Things marked with (*) are forced by default.
-
+.PP
\fIWarning: These options are mostly intended to be used by experts
only. Using them without fully understanding their effects may break
your whole system.\fP
-
+.br
\fBall\fP:
Turns on(or off) all force options.
-
+.br
\fBauto-select\fP(*):
Select packages to install them, and deselect packages to remove them.
-
+.br
\fBdowngrade\fP(*):
Install a package, even if newer version of it is already installed.
-
+.br
\fBconfigure-any\fP:
Configure also any unpacked but unconfigured packages on which the current
package depends.
-
+.br
\fBhold\fP:
Process packages even when marked "hold".
-
+.br
\fBremove-reinstreq\fP:
Remove a package, even if it's broken and marked to require
reinstallation. This may, for example, cause parts of the package to
remain on the system, which will then be forgotten by \fBdpkg\fP.
-
+.br
\fBremove-essential\fP:
Remove, even if the package is considered essential. Essential
packages contain mostly very basic Unix commands. Removing them might
cause the whole system to stop working, so use with caution.
-
+.br
\fBdepends\fP:
Turn all dependency problems into warnings.
-
+.br
\fBdepends-version\fP:
Don't care about versions when checking dependencies.
-
+.br
\fBconflicts\fP:
Install, even if it conflicts with another package. This is dangerous,
for it will usually cause overwriting of some files.
-
+.br
\fBconfmiss\fP:
Always install a missing configuration file. This is dangerous,
since it means not preserving a change (removing) made to the
file.
-
+.br
\fBconfnew\fP:
If a conffile has been modified always install the new version without
prompting, unless the \fB--force-confdef\fP is also specified, in
which case the default action is preferred.
-
+.br
\fBconfold\fP:
If a conffile has been modified always keep the old version without
prompting, unless the \fB--force-confdef\fP is also specified, in
which case the default action is preferred.
-
+.br
\fBconfdef\fP:
If a conffile has been modified always choose the default action. If
there is no default action it will stop to ask the user unless
\fB--force-confnew\fP or \fB--force-confold\fP is also been given, in
which case it will use that to decide the final action.
-
+.br
\fBoverwrite\fP:
Overwrite one package's file with another's file.
-
-\fBoverwrite-dir\fP
+.br
+\fBoverwrite-dir\fP:
Overwrite one package's directory with another's file.
-
+.br
\fBoverwrite-diverted\fP:
Overwrite a diverted file with an undiverted version.
-
+.br
\fBarchitecture\fP:
Process even packages with the wrong architecture.
-
+.br
\fBbad-path\fP:
\fBPATH\fP is missing important programs, so problems are likely.
-
+.br
\fBnot-root\fP:
Try to (de)install things even when not root.
-
+.br
.TP
\fB--ignore-depends\fP=\fIpackage\fP,...
Ignore dependency-checking for specified packages (actually, checking is
@@ -431,11 +421,11 @@
Do everything which is supposed to be done, but don't write any
changes. This is used to see what would happen with the specified
action, without actually modifying anything.
-
+.PP
Be sure to give \fB--no-act\fP before the action-parameter, or you might
end up with undesirable results. (e.g. \fBdpkg --purge foo
--no-act\fP will first purge package foo and then try to purge package
---no-act, even though you probably expected it to actually do nothing)
+--no-act, even though you probably expected it to actually do nothing!)
.TP
\fB-R\fP | \fB--recursive\fP
Recursively handle all regular files matching pattern \fB*.deb\fP
@@ -471,6 +461,7 @@
\fB--status-fd \fP\fI<n>\fP
Send package status info to file descriptor \fI<n>\fP. This can be given
multiple times. Status updates are of the form `status: <pkg>: <pkg qstate>'.
+..
.SH FILES
.TP
.I /etc/dpkg/dpkg.cfg
@@ -502,7 +493,7 @@
.I prerm
.TP
.I postrm
-
+..
.SH ENVIRONMENT VARIABLES
.TP
.B DPKG_NO_TSTP
@@ -525,28 +516,20 @@
Set by \fBdpkg\fP to the filename of the newversion of a configuration file
when you start a shell to examine a changed configuration.
file.
-
+..
.SH EXAMPLES
-To list packages related to the editor vi:
+To list packages containing the string `vi' in their name:
.br
\fB dpkg -l '*vi*'\fP
-.br
-
-To see the entries in \fI/var/lib/dpkg/available\fP on two packages:
+.PP
+To see the entries in \fI/var/lib/dpkg/available\fP on several packages:
.br
-\fB dpkg --print-avail elvis vim | less\fP
-.br
-
-To search the listing of packages yourself:
-.br
-\fB less /var/lib/dpkg/available\fP
-.br
-
-To remove an installed elvis package:
+\fB dpkg -p base-files login xfree86-common | pager\fP
+.PP
+To remove an installed package named "elvis":
.br
\fB dpkg -r elvis\fP
-.br
-
+.PP
To install a package, you first need to find it in an archive or
CDROM. The "available" file shows that the vim package is in section
"editors":
@@ -554,12 +537,12 @@
\fB cd /cdrom/hamm/hamm/binary/editors\fP
\fB dpkg -i vim_4.5-3.deb\fP
.br
-
+(Note: \fBapt-get\fP(8) is commonly used for this.)
+.PP
To make a local copy of the package selection states:
.br
\fB dpkg --get-selections >myselections\fP
-.br
-
+.PP
You might transfer this file to another computer, and install it there
with:
.br
@@ -569,23 +552,32 @@
set the selection state on the requested packages. You will need some
other application to actually download and install the requested
packages.
-
+.PP
Ordinarily, you will find that \fBdselect\fP(8) provides a more
convenient way to modify the package selection states.
-.br
+..
.SH SEE ALSO
-\fBdselect\fP(8),
-\fBdpkg-deb\fP(1),
-\fBdeb\fP(5),
-and
-\fBdeb-control\fP(5)
-
-.SH BUGS
-
-\fB--no-act\fP usually gives less information than might be helpful.
-
+.BR dpkg-deb (1),
+.BR deb (5),
+.BR deb-control (5),
+.BR dselect (8),
+.BR apt (8).
+..
+.SH BUGS/RESTRICTIONS
+dpkg doesn't do any intelligent package ordering on installation.
+.br
+There is no automatic logging ability in dpkg.
+.br
+Depending package relations may sometimes get out of sync on upgrades
+(e.g. exact dependencies of a library -dev package on the library package).
+.PP
+The --no-act option usually gives less information than might be helpful.
+.br
+There is no --status information for virtual packages.
+..
.SH AUTHORS
.nf
-See \fB/usr/share/doc/dpkg/THANKS\fP for the list of people who have
-contributed to \fBdpkg\fP .
+\fBdpkg\fP was originally written by Ian Jackson, and later updated by
+many other people, full list of which you may find in the
+\fB/usr/share/doc/dpkg/THANKS\fP file.
.fi
Index: man/en/dpkg.8.sgml
===================================================================
RCS file: /cvs/dpkg/dpkg/man/en/dpkg.8.sgml,v
retrieving revision 1.5
diff -u -r1.5 dpkg.8.sgml
--- man/en/dpkg.8.sgml 2002/05/13 21:00:32 1.5
+++ man/en/dpkg.8.sgml 2002/06/21 23:04:46
@@ -10,7 +10,7 @@
<refnamediv>
<refname>dpkg</refname>
- <refpurpose>a medium-level package manager for Debian</refpurpose>
+ <refpurpose>medium-level package manager for Debian</refpurpose>
</refnamediv>
@@ -37,6 +37,11 @@
packages. The descriptions of what <command>dpkg</command> does when
installing and removing packages are particularly inadequate.
</para>
+
+ <para>
+ For information about this, please refer to sections regarding the
+ Debian packaging system in the Debian FAQ or in the Debian Reference.
+ </para>
</refsect1>
@@ -45,10 +50,7 @@
<para>
<command>dpkg</command> is a medium-level tool to install, build, remove
- and manage Debian packages. The primary and more user-friendly front-end
- for <command>dpkg</command> is <command>dselect</command> (see
- <citerefentry><refentrytitle>dselect</refentrytitle>
- <manvolnum>8</manvolnum></citerefentry>). <command>dpkg</command> itself
+ and manage Debian packages. <command>dpkg</command>
is controlled entirely via command line parameters, which consist of
exactly one action and zero or more options. The action-parameter tells
<command>dpkg</command> what to do and options control the behavior of
@@ -80,6 +82,15 @@
<manvolnum>1</manvolnum> </citerefentry> for information about these
actions.
</para>
+
+ <para>
+ Note: the primary and more user-friendly front-end for
+ <command>dpkg</command> is <command>dselect</command> (see
+ <citerefentry><refentrytitle>dselect</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry>). There are other front-ends
+ such as those based on <citerefentry><refentrytitle>apt</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry>.
+ </para>
</refsect1>
<refsect1>
@@ -721,7 +732,7 @@
</term>
<listitem><para>
- Display a brief help message.
+ Display the usage instructions.
</para></listitem>
</varlistentry>
@@ -764,14 +775,14 @@
<arg choice="plain">
<group choice="req">
<arg>--licence</arg>
- <arg>--license </arg>
+ <arg>--license</arg>
</group>
</arg>
</cmdsynopsis>
</term>
<listitem><para>
- Display <command>dpkg</command> licence.
+ Display <command>dpkg</command> copyright and licence information.
</para></listitem>
</varlistentry>
@@ -1215,7 +1226,7 @@
(e.g. <screen>dpkg --purge foo --no-act</screen> will first
purge package foo and then try to <command>purge</command>
package --no-act, even though you probably expected it to
- actually do nothing)
+ actually do nothing!)
</para>
</listitem>
</varlistentry>
@@ -1432,26 +1443,20 @@
<title>Examples</title>
<para>
- To list packages related to the editor vi:
+ To list packages containing the string `vi' in their name:
<Screen><command>dpkg</command> <option>-l</option> '*vi*'</Screen>
</para>
- <para>
- To see the entries in <filename>/var/lib/dpkg/available</filename> on two
- packages
-
- <Screen><command>dpkg</command> <option>--print-avail</option> elvis vim</Screen>
- </para>
-
<para>
- To search the listing of packages yourself:
+ To see the entries in <filename>/var/lib/dpkg/available</filename> on
+ several packages:
- <Screen><command>less</command> <filename>/var/lib/dpkg/available</filename></Screen>
+ <Screen><command>dpkg</command> <option>--print-avail</option> base-files login xfree86-common | pager</Screen>
</para>
<para>
- To remove an installed emacs package:
+ To remove an installed package named "emacs":
<Screen><command>dpkg</command> <option>-r</option> emacs</Screen>
</para>
@@ -1487,11 +1492,6 @@
<para>
<citerefentry>
- <refentrytitle>dselect</refentrytitle>
- <manvolnum>8</manvolnum>
- </citerefentry>,
-
- <citerefentry>
<refentrytitle>dpkg-deb</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>,
@@ -1504,7 +1504,17 @@
<citerefentry>
<refentrytitle>deb-control</refentrytitle>
<manvolnum>5</manvolnum>
- </citerefentry>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>dselect</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>apt</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>.
</para>
</refsect1>
</refentry>
Reply to: