Essential package-description review
To pass the time while the Smith Project is on hold I've been going
through the two dozen Essential packages in Lenny and looking at
their descriptions. The ones that needed it I've already been going
ahead and submitting bugreports for (at Severity: normal or
Severity: minor), but here are reviews of the others in case anyone
wants to comment.
I'm also open to suggestions about types of package to target next.
======================================================================
# Package: apt
# Description: Advanced front-end for dpkg
# This is Debian's next generation front-end for the dpkg package manager.
# It provides the apt-get utility and APT dselect method that provides a
# simpler, safer way to install and upgrade packages.
# .
# APT features complete installation ordering, multiple source capability
# and several other unique features, see the Users Guide in apt-doc.
See (my follow-up to) bug #458029.
----------------------------------------------------------------------
# Package: base-files
# Description: Debian base system miscellaneous files
# This package contains the basic filesystem hierarchy of a Debian system, and
# several important miscellaneous files, such as /etc/debian_version,
# /etc/host.conf, /etc/issue, /etc/motd, /etc/profile, /etc/nsswitch.conf,
# and others, and the text of several common licenses in use on Debian systems.
That's not precisely how I'd have phrased it - the list is weaselled
at both ends and has too many "and"s:
This package contains the basic filesystem hierarchy of a Debian system,
plus several important miscellaneous files, such as /etc/debian_version,
/etc/host.conf, /etc/issue, /etc/motd, /etc/profile, and /etc/nsswitch.conf,
as well as the text of several commonly used software licenses.
(Does /etc/profile belong on this list? It's created by the
postinst, not directly contained as a configfile...)
But this definitely isn't worth the effort.
----------------------------------------------------------------------
# Package: base-passwd
# Description: Debian base system master password and group files
# These are the canonical master copies of the user database files
# (/etc/passwd and /etc/group), containing the Debian-allocated user and
# group IDs. The update-passwd tool is provided to keep the system databases
# synchronized with these master files.
"These" in the long description refers back to the files mentioned
in the short description, which seems like a bad idea, but that's
all I can see to complain about.
----------------------------------------------------------------------
# Package: bash
# Description: The GNU Bourne Again SHell
# Bash is an sh-compatible command language interpreter that executes
# commands read from the standard input or from a file. Bash also
# incorporates useful features from the Korn and C shells (ksh and csh).
# .
# Bash is ultimately intended to be a conformant implementation of the
# IEEE POSIX Shell and Tools specification (IEEE Working Group 1003.2).
# .
# The Programmable Completion Code, by Ian Macdonald, is now found in
# the bash-completion package.
* Bogus capitalised article in synopsis.
* Why capitalised "Programmable Completion Code"?
I'd like this better if instead of all the standards-compliance
details it included some hint at the fact that this package provides
the command-line interface that normal users get when they invoke a
terminal... but never mind, I think on balance I'll leave it.
----------------------------------------------------------------------
# Package: bsdutils
# Description: Basic utilities from 4.4BSD-Lite
# This package contains the bare minimum number of BSD utilities needed
# to boot a Debian system. You should probably also install
# bsdmainutils to get the remaining standard BSD utilities.
# .
# Included are: cal, col, colcrt, colrm, column, logger, renice,
# script, scriptreplay, ul, wall
A pack of lies. See bug #482098.
----------------------------------------------------------------------
# Package: coreutils
# Description: The GNU core utilities
# This package contains the essential basic system utilities.
# .
# Specifically, this package includes:
# basename cat chgrp chmod chown chroot cksum comm cp csplit cut date dd df dir
# dircolors dirname du echo env expand expr factor false fmt fold groups head
# hostid id install join link ln logname ls md5sum mkdir mkfifo mknod mv nice nl
# nohup od paste pathchk pinky pr printenv printf ptx pwd readlink rm rmdir
# sha1sum seq shred sleep sort split stat stty sum sync tac tail tee test touch
# tr true tsort tty uname unexpand uniq unlink users vdir wc who whoami yes
* Bogus capitalised article in synopsis.
* The use of "core", "essential" and "basic" is repetition in place
of explanation.
* An alternative approach to list sententialisation. Fair enough
with one this length.
So perhaps (stealing some text from gnu.org):
Description: GNU core utilities
This package contains the basic file, shell and text manipulation utilities
which are expected to exist on every operating system.
.
Specifically, this package includes:
[etc]
But this may or may not be worth the effort.
----------------------------------------------------------------------
# Package: debianutils
# Description: Miscellaneous utilities specific to Debian
# This package provides a number of small utilities which are used
# primarily by the installation scripts of Debian packages, although
# you may use them directly.
# .
# The specific utilities included are: installkernel mkboot run-parts
# savelog sensible-browser sensible-editor sensible-pager tempfile
# which.
* Bogus capitalisation in synopsis.
* What happened to (/usr/sbin/)add-shell and remove-shell?
* I'd be happier if this decided whether it wanted to be a sentence:
The specific utilities included are add-shell, installkernel, mkboot,
remove-shell, run-parts, savelog, sensible-browser, sensible-editor,
sensible-pager, tempfile, and which.
or a raw list:
The specific utilities included are:
add-shell installkernel mkboot remove-shell run-parts savelog
sensible-browser sensible-editor sensible-pager tempfile which
But again not a high-priority one to revise.
----------------------------------------------------------------------
# Package: diff
# Description: File comparison utilities
# The diff package provides the diff, diff3, sdiff, and cmp programs.
# .
# `diff' shows differences between two files, or each corresponding file
# in two directories. `cmp' shows the offsets and line numbers where
# two files differ. `cmp' can also show all the characters that
# differ between the two files, side by side. `diff3' shows differences
# among three files. `sdiff' merges two files interactively.
# .
# The set of differences produced by `diff' can be used to distribute
# updates to text files (such as program source code) to other people.
# This method is especially useful when the differences are small compared
# to the complete files. Given `diff' output, the `patch' program can
# update, or "patch", a copy of the file.
* Bogus capitalisation in synopsis.
* Nonstandard spacing.
* Two different quoting styles: TeXish `quotes' as a substitute for
<code>...</code>, unTeXish "scare-quotes" on the last line.
If diff is commonly used with patch, why doesn't diff have a
"Suggests: patch"? This text doesn't even name the package that
contains /usr/bin/patch, giving the false impression it's included
in this package.
Not worth a bug report, though.
----------------------------------------------------------------------
# Package: dpkg
# Description: package maintenance system for Debian
# This package contains the low-level commands for handling the installation
# and removal of packages on your system.
# .
# In order to unpack and build Debian source packages you will need to
# install the developers' package `dpkg-dev' as well as this one.
See #484002, Severity: minor.
----------------------------------------------------------------------
# Package: e2fsprogs
# Description: ext2 file system utilities and libraries
# EXT2 stands for "Extended Filesystem", version 2. It's the main
# filesystem type used for hard disks on Debian and other Linux systems.
# .
# This package contains programs for creating, checking, and maintaining EXT2
# filesystems, and the generic `fsck' wrapper.
See #483023 (fixed in the VCS).
----------------------------------------------------------------------
# Package: findutils
# Description: utilities for finding files--find, xargs
# GNU findutils provides utilities to find files meeting specified
# criteria and perform various actions on the files which are found.
# This package contains 'find' and 'xargs'; however, 'locate' has
# been split off into a separate package.
This is one I nagged into shape a while ago (bug #455690), though I
wouldn't have recommended some of that punctuation.
----------------------------------------------------------------------
# Package: grep
# Description: GNU grep, egrep and fgrep
# 'grep' is a utility to search for text in files; it can be used from the
# command line or in scripts. Even if you don't want to use it, other packages
# on your system probably will.
# .
# The GNU family of grep utilities may be the "fastest grep in the west".
# GNU grep is based on a fast lazy-state deterministic matcher (about
# twice as fast as stock Unix egrep) hybridized with a Boyer-Moore-Gosper
# search for a fixed string that eliminates impossible text from being
# considered by the full regexp matcher without necessarily having to
# look at every character. The result is typically many times faster
# than Unix grep or egrep. (Regular expressions containing backreferencing
# will run more slowly, however.)
* Nonstandard spacing and quotes.
* The lowercase initial "grep" could be buffered with something like
"This package provides grep, a utility..."
* Unnecessarily personal. Never mind whether I "want" to use grep -
dpkg says it's essential.
* The second paragraph is more than I thought I needed to know.
All of this is minor niggling, though; it'll do.
----------------------------------------------------------------------
# Package: gzip
# Description: The GNU compression utility
# This is the standard GNU file compression utility, which is also the default
# compression tool for Debian. It typically operates on files with names
# ending in '.gz'.
# .
# This package can also decompress '.Z' files created with 'compress'.
See #484547 (Severity: minor).
----------------------------------------------------------------------
# Package: hostname
# Description: utility to set/show the host name or domain name
# The hostname command can be used to either set or display the current host or
# domain name of the system. This name is used by many of the networking programs
# to identify the machine. The domain name is also used by NIS/YP.
Misleading; see bug #483221.
----------------------------------------------------------------------
# Package: login
# Description: system login tools
# These tools are required to be able to login and use your system. The
# login program invokes your user shell and enables command execution. The
# newgrp program is used to change your effective group ID (useful for
# workgroup type situations). The su program allows changing your effective
# user ID (useful being able to execute commands as another user).
This feels non-native-English-speakerish, using contorted passive
constructions where it would have been quite entitled to use the
generic second person pronouns throughout. (Also, you can "use" a
system for a variety of things without necessarily logging in.)
This package provides tools which are required for logging into a system.
The login program invokes your user shell and enables command execution.
The newgrp program changes your effective group ID (useful for situations
such as workgroups). The su program changes your effective user ID
(allowing you to execute commands as another user).
The package also contains faillog, lastlog, nologin and sg, but I
suppose we can ignore them; in fact I'm not sure there's any real
need to mention newgrp.
----------------------------------------------------------------------
# Package: mktemp
# Description: Makes unique filenames for temporary files
# Mktemp is a simple utility designed to make temporary file handling
# in shells scripts be safe and simple.
See bug #482666; I may inadvertently have triggered the package's
eventual demise.
----------------------------------------------------------------------
# Package: mount
# Description: Tools for mounting and manipulating filesystems
# This package provides the mount(8), umount(8), swapon(8),
# swapoff(8), and losetup(8) commands.
Bogus capitalisation in the synopsis.
Manpage references in package descriptions are generally a bad idea.
In an Essential package it's relatively harmless (you aren't telling
users "this package provides utilities you can only find out about
if you install it first"), but it's still neutral at best - after
all, if a package provided commands that _didn't_ come with manual
pages, that would be a bug. It would be more helpful to point out
that this package provides nfs(5) and fstab(5)!
Instead I'd recommend simply:
Description: tools for mounting and manipulating filesystems
This package provides the mount, umount, swapon, swapoff, and losetup
commands.
----------------------------------------------------------------------
# Package: ncurses-base
# Description: Descriptions of common terminal types
# This package contains what should be a reasonable subset of terminal
# definitions, including: ansi, dumb, linux, rxvt, screen, sun, vt100,
# vt102, vt220, vt52, and xterm.
See #484172 (Severity: minor).
----------------------------------------------------------------------
# Package: ncurses-bin
# Description: Terminal-related programs and man pages
# This package contains the programs used for manipulating the terminfo
# database and individual terminfo entries, as well as some programs for
# resetting terminals and such.
* Bogus capitalisation in synopsis.
* No need to mention the man pages - their absence would be a bug.
* "And such" seems informal, but that may just be a dialect issue.
----------------------------------------------------------------------
# Package: perl-base
# Description: The Pathologically Eclectic Rubbish Lister
# A scripting language with delusions of full language-hood, Perl is used
# in many system scripts and utilities.
# .
# This is a stripped down Perl with only essential libraries. To make
# full use of Perl, you'll want to install the `perl', `perl-modules' and
# optionally `perl-doc' packages which supplement this one.
See #484681 (the last and least Severity: minor); I accidentally got
more than I wanted.
----------------------------------------------------------------------
# Package: sed
# Description: The GNU sed stream editor
# sed reads the specified files or the standard input if no
# files are specified, makes editing changes according to a
# list of commands, and writes the results to the standard
# output.
* Bogus capitalised article.
* Should there be some sort of frame of "this package provides just
one standard text-manipulating utility" around the manpagey
stuff? (It would also get the "s" out of initial position.)
----------------------------------------------------------------------
# Package: sysvinit
# Description: System-V-like init utilities
# This package contains programs required for booting
# a Debian system and doing basic process management.
# .
# The most important program in the package is /sbin/init.
# It is the first process started on boot and continues
# to run as process number 1 until the system halts. All
# other processes are descended from it.
The only thing I'd question here is whether the synopsis should be
modified to fit better alongside sysvinit-utils:
Description: System-V-based init infrastructure
(After all, it contains /etc/inittab and everything.)
----------------------------------------------------------------------
# Package: sysvinit-utils
# Description: System-V-like utilities
# This package contains the important System-V-like utilities.
# .
# Specifically, this package includes:
# killall5, last, lastb, mesg, pidof, sulogin
Saying these utilities are "System-V-like" isn't quite right - it
suggests that pidof and the others resemble the System V UNIX
operating system. Instead it's code for "part of the set of
utilities characteristic of UNIX but not inherited by way of BSD".
Perhaps it would be more useful to say that they're tools
connected with the sysvinit package:
Description: System-V-based init utilities
This package contains essential utilities associated with the
System V init process: killall5, last, lastb, mesg, pidof, and
sulogin.
If I was convinced this was the best approach I'd submit the
bugreport.
----------------------------------------------------------------------
# Package: tar
# Description: GNU version of the tar archiving utility
# Tar is a program for packaging a set of files as a single archive in tar
# format. The function it performs is conceptually similar to cpio, and to
# things like PKZIP in the DOS world. It is heavily used by the Debian package
# management system, and is useful for performing system backups and exchanging
# sets of files with others.
* Nonstandard spacing.
* "Packaging" is misleading (especially when it goes on to say that
it's used in the Debian package management system).
* Outdated; how many people coming to Debian today are likely to be
coming from "the DOS world"? Let alone finding cpio a good
analogy for understanding tar? These days even Macs use
zip...
It seems to me we'd be better off with:
Tar is a program for bundling up a set of files as a single archive in tar
format, functionally similar to the zip format commonly used on other
operating systems. Tar is heavily used by the Debian package management
system, and is useful for performing system backups and exchanging sets of
files with others.
----------------------------------------------------------------------
# Package: util-linux
# Description: Miscellaneous system utilities
# This package contains a number of important utilities, most of which
# are oriented towards maintenance of your system. Some of the more
# important utilities included in this package allow you to partition
# your hard disk, view kernel messages, and create new filesystems.
* Bogus capitalisation in synopsis.
* Inapropriate personalisation (I may be maintaining the company's
system, or partitioning a friend's hard disk).
* Nonstandard spacing.
* Given that there are forty of them, many of which are genuinely
essential, this seems understated for once!
Maybe something like:
Description: miscellaneous system utilities
This package contains many utilities essential for system maintenance,
including tools to partition hard disks, create new file systems, and
view kernel messages.
======================================================================
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about any of the above packages
Reply to: