Bug#490918: debian-refcard: corrections and suggestions
Package: debian-refcard
Version: 0.3.2-1
Severity: wishlist
Tags: patch
A patch is attached; here's my commentary. Of course, applying the
patch as-is would give you a truncated and misorganised reference
card, so my general comments at the end also include a few suggested
topics for replacement entries.
- <glossentry id="boot-expert">
- <glossterm><literal>boot: expert</literal></glossterm>
- <glossdef><para>E.g. to set up the network w/o DHCP or using
- LILO instead of GRUB.</para></glossdef>
- </glossentry>
- <glossentry id="boot-26">
- <glossterm><literal>boot: linux26</literal> or <literal>boot:
- expert26</literal></glossterm>
- <glossdef><para>Use Linux kernel 2.6 for
- installation.</para></glossdef>
- </glossentry>
These boot options are distinctly Oldstablish; Lenny doesn't support
Linux 2.4, and its GUI installer has a menu item for "expert mode".
- <glossentry id="nano">
- <glossterm>nano <replaceable>files</replaceable></glossterm>
- <glossdef><para>Default text editor. If not present, try
- <command>emacs</command>, <command>vi</command>,
- <command>joe</command>.</para></glossdef>
- </glossentry>
+ <glossentry id="editor">
+ <glossterm>editor <replaceable>files</replaceable></glossterm>
+ <glossdef><para>Invokes the system default text editor (which
+ may be <command>nano</command>, <command>emacs</command>,
+ <command>vi</command>, <command>joe</command>...).</para></glossdef>
</glossentry>
Instead of trying to guess what's installed, we can rely on the
power of Debian! The best available editor is the one called
/usr/bin/editor.
(Note my restraint here in leaving emacs and vi on the list! I'm
already on record as believing that neither of the two are entitled
to be described to new users as general-purpose text editors.)
- <glossentry id="webmin">
- <glossterm><ulink url="https://localhost:10000";>webmin</ulink>
- at <literal>https://hostname:10000</literal></glossterm>
- <glossdef><para>Browser interface to system configuration,
- access is defined in
- <filename>/etc/webmin/miniserv.conf</filename>.</para></glossdef>
Cut the webmin reference; webmin isn't in Etch, let alone Lenny.
<glossentry id="dpkg-reconfigure">
<glossterm>dpkg-reconfigure
<replaceable>package-name</replaceable></glossterm>
<glossdef><para>Reconfigure a package, e.g. console-common
- (keyboard), locales (localisation).</para></glossdef>
+ (keyboard), locales (localization).</para></glossdef>
</glossentry>
(I use en_GB, but the debian-l10n-english standard is en_US.)
<glossentry id="update-alternatives">
<glossterm>update-alternatives
<replaceable>options</replaceable></glossterm>
<glossdef><para>Manage command alternatives.</para></glossdef>
</glossentry>
<glossentry id="update-grub">
<glossterm>update-grub</glossterm>
- <glossdef><para>After installing a new
+ <glossdef><para>After installing a new non-Debian
kernel.</para></glossdef>
</glossentry>
Packaged kernels do the update-grub for you; indeed, this is a
utility that normal users don't really need to know about.
- <glossentry id="less">
- <glossterm>less <replaceable>files</replaceable></glossterm>
- <glossdef><para>Show contents of files.</para></glossdef>
+ <glossentry id="pager">
+ <glossterm>pager <replaceable>files</replaceable></glossterm>
+ <glossdef><para>Show contents of files using the system
+ default pager (usually <literal>less</literal>).</para></glossdef>
</glossentry>
The package "less" is only Priority: standard (and has alternatives
such as "most"), which means that the likelihood of it being
available is _lower_ than for "nano" (Priority: important and used
in debian-installer). So again, trust /etc/alternatives.
<glossentry id="apt-get-update">
<glossterm>apt-get update</glossterm>
<glossdef><para>Update packages listings from package
repositories as listed in
- <filename>/etc/apt/sources.list</filename>. Run, if the
- contents of one of repositories, the file changed, or if
- unsure.</para></glossdef>
+ <filename>/etc/apt/sources.list</filename>. Required whenever that
+ file or the contents of the repositories change.</para></glossdef>
</glossentry>
Fixing the broken English.
<glossentry id="apt-cache-depends">
<glossterm>apt-cache depends
<replaceable>package-names</replaceable></glossterm>
- <glossdef><para>List all packages needed by the
+ <glossdef><para>List all packages needed by the one
given.</para></glossdef>
</glossentry>
<glossentry id="apt-cache-rdepends">
<glossterm>apt-cache rdepends
<replaceable>package-names</replaceable></glossterm>
- <glossdef><para>List all packages that need the
+ <glossdef><para>List all packages that need the one
given.</para></glossdef>
</glossentry>
Improving the slightly broken English. I'd have phrased it as "all
packages that depend on the one specified", but then again this _is_
quite a bit shorter.
<glossentry id="deborphan">
<glossterm>deborphan</glossterm>
- <glossdef><para>Show packages, on that no other packages
- depend (<emphasis>orphans</emphasis>), needs
+ <glossdef><para>Show packages that no other packages
+ depend on (<emphasis>orphans</emphasis>); needs
<literal>deborphan</literal>.</para></glossdef>
</glossentry>
Fixing the broken English. Actually these days I wouldn't bother
telling newbies about "deborphan" when they can get the same thing
from aptitude. I'm not sure I'd even tell them about apt-get.
<glossentry id="dpkg-divert">
<glossterm>dpkg-divert <optional>options</optional>
<replaceable>file</replaceable></glossterm>
<glossdef><para>Override a package's version of a
file.</para></glossdef>
</glossentry>
(And I certainly wouldn't tell them about dpkg-divert.)
<section id="network">
<title>The Network</title>
<glosslist>
<glossentry id="sbin-ifconfig">
<glossterm>/sbin/ifconfig</glossterm>
<glossdef><para>Configure network
interfaces.</para></glossdef>
</glossentry>
("ifconfig" is being slowly deprecated in favour of the tools in
iproute2. However, it's still more likely to be installed.)
- <glossentry id="etc-network">
- <glossterm><filename>/etc/network/</filename></glossterm>
- <glossdef><para>Network configuration files, most relevant are
- <filename>interfaces</filename> and
- <filename>options</filename>.</para></glossdef>
+ <glossentry id="etc-network-interfaces">
+ <glossterm><filename>/etc/network/interfaces</filename></glossterm>
+ <glossdef><para>Network interface configuration.</para></glossdef>
/etc/network/options has been deprecated since Etch. Once that's
gone, I'm not sure if the item's worth keeping - after all, there's
no entry for /etc/fstab or /etc/X11/xorg.conf.
<glossentry id="etc-apache2-mods-available">
<glossterm><filename>/etc/apache2/mods-available/</filename></glossterm>
<glossdef><para>Contains available modules files. To enable a
- module, create a symbolic link into
- <filename>/etc/apache2/mods-enabled/</filename>.</para></glossdef>
+ module, use <literal>/usr/sbin/a2enmod</literal>.</para></glossdef>
</glossentry>
</glosslist>
</section>
Don't create symlinks by hand - see a2enmod(8). In fact I'm not
sure reconfiguration techniques for one particular webserver deserve
a place on this list. And as for:
<section id="postgresql">
<title>Database (PostgreSQL)</title>
This stuff certainly doesn't belong on a list of the top things you
_need_ to know; I've been using Debian for twelve years without ever
once needing to install PostgreSQL. I'd be in favour of ripping out
the whole section and replacing it with mentions of more important
packages, such as iptables or mount or procps or apt-listbugs or
apt-listchanges or cron-apt or debtags or locate(/mlocate/slocate)
or dlocate or anacron or file or mime-support or mc or logcheck...
Other half-baked comments:
Couldn't you get through half of the entries in a single go by
listing the command names and saying "Read The Fine Manual"? Or
indeed:
whatis $( echo ${PATH//:/ } | xargs -n1 ls | sort -u )
On the other hand, you should probably also mention info, especially
when it comes to tricky cases like "info coreutils".
Also, wouldn't it make sense to factor some things out into
footnotes, like this?
deborphan¹ blah blah
cf. synaptic¹²
chown² <user>:<group> <file>
[...]
Footnotes:
1) requires the installation of the package of this name.
2) requires root privileges.
-- System Information:
Debian Release: lenny/sid
APT prefers testing
APT policy: (500, 'testing'), (50, 'unstable')
Architecture: i386 (i586)
Kernel: Linux 2.6.25.custom
Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
debian-refcard depends on no packages.
Versions of packages debian-refcard recommends:
ii gv [pdf-viewer] 1:3.6.4-3 PostScript and PDF viewer for X
ii xpdf-reader [pdf-viewer] 3.02-1.3 Portable Document Format (PDF) sui
-- no debconf information
--
JBR
Ankh kak! (Ancient Egyptian blessing)
diff -ru refcard-0.3.2.pristine/entries.dbk refcard-0.3.2/entries.dbk
--- refcard-0.3.2.pristine/entries.dbk 2008-03-03 15:07:51.000000000 +0000
+++ refcard-0.3.2/entries.dbk 2008-07-14 22:47:00.000000000 +0100
@@ -91,17 +91,6 @@
<glossdef><para>Download from
<literal>http://www.debian.org/distrib/</literal></para></glossdef>
</glossentry>
- <glossentry id="boot-expert">
- <glossterm><literal>boot: expert</literal></glossterm>
- <glossdef><para>E.g. to set up the network w/o DHCP or using
- LILO instead of GRUB.</para></glossdef>
- </glossentry>
- <glossentry id="boot-26">
- <glossterm><literal>boot: linux26</literal> or <literal>boot:
- expert26</literal></glossterm>
- <glossdef><para>Use Linux kernel 2.6 for
- installation.</para></glossdef>
- </glossentry>
</glosslist>
</section>
<section id="bugs">
@@ -141,18 +130,11 @@
<glossdef><para>All system configuration files are under
directory <filename>/etc/</filename>.</para></glossdef>
</glossentry>
- <glossentry id="nano">
- <glossterm>nano <replaceable>files</replaceable></glossterm>
- <glossdef><para>Default text editor. If not present, try
- <command>emacs</command>, <command>vi</command>,
- <command>joe</command>.</para></glossdef>
- </glossentry>
- <glossentry id="webmin">
- <glossterm><ulink url="https://localhost:10000";>webmin</ulink>
- at <literal>https://hostname:10000</literal></glossterm>
- <glossdef><para>Browser interface to system configuration,
- access is defined in
- <filename>/etc/webmin/miniserv.conf</filename>.</para></glossdef>
+ <glossentry id="editor">
+ <glossterm>editor <replaceable>files</replaceable></glossterm>
+ <glossdef><para>Invokes the system default text editor (which
+ may be <command>nano</command>, <command>emacs</command>,
+ <command>vi</command>, <command>joe</command>...).</para></glossdef>
</glossentry>
<glossentry id="cups">
<glossterm><ulink url="http://localhost:631";>CUPS</ulink> at
@@ -164,7 +146,7 @@
<glossterm>dpkg-reconfigure
<replaceable>package-name</replaceable></glossterm>
<glossdef><para>Reconfigure a package, e.g. console-common
- (keyboard), locales (localisation).</para></glossdef>
+ (keyboard), locales (localization).</para></glossdef>
</glossentry>
<glossentry id="update-alternatives">
<glossterm>update-alternatives
@@ -173,7 +155,7 @@
</glossentry>
<glossentry id="update-grub">
<glossterm>update-grub</glossterm>
- <glossdef><para>After installing a new
+ <glossdef><para>After installing a new non-Debian
kernel.</para></glossdef>
</glossentry>
<glossentry id="make-kpkg">
@@ -259,9 +241,10 @@
<replaceable>files</replaceable></glossterm>
<glossdef><para>Compress, uncompress files.</para></glossdef>
</glossentry>
- <glossentry id="less">
- <glossterm>less <replaceable>files</replaceable></glossterm>
- <glossdef><para>Show contents of files.</para></glossdef>
+ <glossentry id="pager">
+ <glossterm>pager <replaceable>files</replaceable></glossterm>
+ <glossdef><para>Show contents of files using the system
+ default pager (usually <literal>less</literal>).</para></glossdef>
</glossentry>
<glossentry id="ls">
<glossterm>ls
@@ -377,9 +360,8 @@
<glossterm>apt-get update</glossterm>
<glossdef><para>Update packages listings from package
repositories as listed in
- <filename>/etc/apt/sources.list</filename>. Run, if the
- contents of one of repositories, the file changed, or if
- unsure.</para></glossdef>
+ <filename>/etc/apt/sources.list</filename>. Required whenever that
+ file or the contents of the repositories change.</para></glossdef>
</glossentry>
<glossentry id="apt-cache-search">
<glossterm>apt-cache search
@@ -430,13 +412,13 @@
<glossentry id="apt-cache-depends">
<glossterm>apt-cache depends
<replaceable>package-names</replaceable></glossterm>
- <glossdef><para>List all packages needed by the
+ <glossdef><para>List all packages needed by the one
given.</para></glossdef>
</glossentry>
<glossentry id="apt-cache-rdepends">
<glossterm>apt-cache rdepends
<replaceable>package-names</replaceable></glossterm>
- <glossdef><para>List all packages that need the
+ <glossdef><para>List all packages that need the one
given.</para></glossdef>
</glossentry>
<glossentry id="apt-file-update">
@@ -505,8 +487,8 @@
</glossentry>
<glossentry id="deborphan">
<glossterm>deborphan</glossterm>
- <glossdef><para>Show packages, on that no other packages
- depend (<emphasis>orphans</emphasis>), needs
+ <glossdef><para>Show packages that no other packages
+ depend on (<emphasis>orphans</emphasis>); needs
<literal>deborphan</literal>.</para></glossdef>
</glossentry>
<glossentry id="debsums">
@@ -556,11 +538,9 @@
<glossdef><para>Configure network
interfaces.</para></glossdef>
</glossentry>
- <glossentry id="etc-network">
- <glossterm><filename>/etc/network/</filename></glossterm>
- <glossdef><para>Network configuration files, most relevant are
- <filename>interfaces</filename> and
- <filename>options</filename>.</para></glossdef>
+ <glossentry id="etc-network-interfaces">
+ <glossterm><filename>/etc/network/interfaces</filename></glossterm>
+ <glossdef><para>Network interface configuration.</para></glossdef>
</glossentry>
<glossentry id="ifup-ifdown">
<glossterm>ifup, ifdown
@@ -596,8 +576,7 @@
<glossentry id="etc-apache2-mods-available">
<glossterm><filename>/etc/apache2/mods-available/</filename></glossterm>
<glossdef><para>Contains available modules files. To enable a
- module, create a symbolic link into
- <filename>/etc/apache2/mods-enabled/</filename>.</para></glossdef>
+ module, use <literal>a2enmod</literal>.</para></glossdef>
</glossentry>
</glosslist>
</section>
Reply to: