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>