Re: improving DevRef 6.2.2
Way back on Tue, 7 Aug last year I wrote:
> I'm thinking of submitting a bugreport against Developers-Reference
> section 6.2.2, and would appreciate any input from d-l-e readers,
> what with there being nothing else going on here at present.
In case anybody ever wondered, this never went anywhere because
apparently I lost the draft I was working on. Doh.
To recap, DevRef says:
######################################################################
# The synopsis line (the short description) should be concise. It
# must not repeat the package's name (this is policy).
#
# It's a good idea to think of the synopsis as an appositive clause,
# not a full sentence. An appositive clause is defined in WordNet as
# a grammatical relation between a word and a noun phrase that
# follows, e.g., "Rudolph the red-nosed reindeer". The appositive
# clause here is "red-nosed reindeer". Since the synopsis is a
# clause, rather than a full sentence, we recommend that it neither
# start with a capital nor end with a full stop (period).
#
# It might help to imagine that the synopsis is combined with the
# package name in the following way:
#
# *package-name* is a *synopsis*.
#
# Alternatively, it might make sense to think of it as
#
# *package-name* is *synopsis*.
#
# or, if the package name itself is a plural (such as
# developers-tools)
#
# *package-name* are *synopsis*.
#
# This way of forming a sentence from the package name and synopsis
# should be considered as a heuristic and not a strict rule. There
# are some cases where it doesn't make sense to try to form a
# sentence.
######################################################################
That second paragraph is where the trouble starts.
First, valid package synopses aren't clauses. Clauses have verbs.
Second, WordNet recognises no such expression as "appositive clause"
("http://wordnet.princeton.edu/perl/webwn?s=appositive+clause";) and
the grammar books that do use the term "appositive clause" use it
quite differently: as an alternative label for reduced relative
clauses (like the capitalised part of "this is the kind IT MEANS").
The WordNet definition quoted is instead taken from its entry for
"apposition". Now, there is such a thing as a noun phrase "in
apposition", also known as an "appositive noun phrase", and package
synopses as they occur in package-lists might be interpreted as
being appositive noun phrases... if it wasn't for the fact
that they drop their initial definite/indefinite article (which is a
constituent of the noun phrase). On the other hand, when they're
padded out to fit the suggested "package-name is a synopsis"
template, yes, then they're full noun phrases... but not appositive
ones.
If you're finding this annoyingly technical, well, that's the bigger
problem. Even if everything else was correct, it wouldn't be "a
good idea" to explain things this way. After all, this synopsis
format isn't recommended on the basis of its superior syntax, it's
just a matter of standardising on common good practice. Software
developers have no reason to know or care about the appropriate
labels for English phrase structures; basing the rule on their
understanding of a particular grammatical analysis is a _bad_ idea.
It's also worth noticing that DevRef's mention of apposition has
nothing to do with the rule against articles (witness the fact that
"Rudolph the red-nosed reindeer" does have a definite article). The
trimming of "a/the" isn't grammatically motivated; it's an extra
rule designed to reduce redundancy.
Okay, here's a delayed 6.2.2 revision draft 2a, which I'm posting to
the list before I accidentally delete it again:
---------------------------------------------------------------------
| Policy says the synopsis line (the short description) must be
| concise, not repeating the package name, but also informative.
|
| The synopsis functions as a phrase describing the package, not as
| a complete sentence, so sentential punctuation is inappropriate:
| it does not need extra capital letters or a final period (full
| stop). It should also omit any initial indefinite or definite
| article ("a(n)/the"). Thus for instance:
|
| libeg0 - exemplification support library
|
| A good heuristic is that it should be possible to substitute the
| package name and synopsis into this formula:
|
| The package "$NAME" provides [a(n)|the|some] $SYNOPSIS.
|
| Sets of related packages may use an alternative scheme that divides
| the synopsis into two parts, the first a description of the whole
| suite and the second a summary of the package's role within it:
|
| eg-tools - simple exemplification system (utilities)
|
| These suite-and-role synopses need a modified formula:
|
| The package "$NAME" provides [a...] $ROLE for [a...] $SUITE
---------------------------------------------------------------------
I could add a couple of lines about the pros and cons of the two
schemes, but they're probably obvious. I prefer "provides" to "is"
on the ultra-pedantic grounds that
eg-data is a single fifty-megabyte ASCII text file
wouldn't exactly be true - the package is a compressed ar-ball,
which also contains a /usr/share/doc/eg-data directory, etcetera.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: