improving DevRef 6.2.2
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.
DevRef 6.2.2:
# The synopsis line (the short description) should be concise. It
# must not repeat the package's name (this is policy).
That paragraph's fine.
# 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".
If WordNet really defined "appositive clause" this way (I don't see
it: "http://wordnet.princeton.edu/perl/webwn?s=appositive+clause";),
it would be wrong. A clause isn't a "relation", it's a syntactic
constituent. In particular, it's a constituent which must at a
minimum include a verb, and there's no verb here. You might use
"red-nosed reindeer" as part of a clause involving a Claus, but it
isn't an "appositive clause", it's an "appositive phrase".
Strictly speaking, "red-nosed reindeer" isn't a full "noun phrase",
either, once you've amputated its definite article. But what I'd
like to propose is that the DevRef should avoid trying to define
things like this; DDs don't need to know the jargon, they just need
a couple of examples and a rule of thumb.
# 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).
Apart from anything else, this is misleadingly phrased: the synopsis
_can_ begin with a capital letter, if for instance the first word is
"DNS". But it has already been pointed out that the synopsis isn't
a sentence; it follows that there's no need for sentential
punctuation (including sentential capitalisation).
I'd also reverse "full stop" and "period" here; the en_US term is
probably more widely recognised than its en_GB equivalent.
# It should also not begin with an article, either definite ("the")
# or indefinite ("a" or "an").
Dropping initial articles is a third independent rule - one of
writing style, rather than of correct grammar or punctuation. The
style we're aiming at for Debian package synopses is slightly more
concise than the style used for titles of works of fiction, where
initial articles are often but not always dropped ("[The] War of the
Worlds"); and it's slightly less telegraphic than newspaper headline
style, where other words may also be omitted ("MAN BITES DOG"). It
makes most sense when compared to other classificatory catalogues:
Platoon - war movie
Akira - subtitled Japanese animation
Life On Earth - natural history documentary
Unfortunately I can't think of any "canonical" examples of this
style. Any suggestions?
First draft replacement version of that paragraph:
The synopsis is an appositive phrase describing the package. Since
it isn't a complete sentence, sentential punctuation is
inappropriate: it does not need initial capitalization or a final
period (full stop). It should also omit any initial article,
either definite ("the") or indefinite ("a" or "an").
The rest of the section reads as follows:
# 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.
This is a surprisingly defeatist way of looking at it! To me it
seems easily within reach of a foolproof algorithmic check:
The package "$NAME" provides [the|a(n)|some] $SYNOPSIS.
Are there any (valid) synopses that don't fit this formula?
--
JBR
Ankh kak! (Ancient Egyptian blessing)
Reply to: