DevRef 6.2.2, round three
The Developers Reference section on short descriptions was developed
here on d-l-e, so I'd like to open a discussion of bug #536889 here
too. The current text (online, but not in Sid yet) has:
#---------------------------------------------------------------------
# The synopsis functions as a phrase describing the package, not 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", "an", or "the". Thus for instance:
#
# Package: libeg0
# Description: exemplification support library
#
# Technically this is a noun phrase minus articles, as opposed to a
# verb phrase. A good heuristic is that it should be possible to
# substitute the package name and synopsis into this formula:
#
# The package <name> provides {a,an,the,some} <synopsis>.
#---------------------------------------------------------------------
Criticisms:
1) basically, it's not clear that verb phrases are the main thing
we're deprecating;
2) in particular, the "noun phrase/verb phrase" part can be read as
an incidental description of the given example;
3) more examples (both "should" and "should not") would be good;
4) "a good heuristic" also makes it sound as if fitting the template
is optional. (Yes, the underlying definition is a matter of
syntax, but since developers don't usually think in terms of
noun phrases or verb phrases, the "heuristic" is the only
practical validation mechanism.)
A revised draft:
----------------------------------------------------------------------
| The synopsis functions as a noun 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", "an", or "the". Thus for instance:
|
| Package: libeg0
| Description: exemplification support library
|
| Package: xeg
| Description: lightweight graphical example browser
|
| Package: ttf-eg
| Description: sample TrueType fonts
|
| Although verb phrases (such as "create examples" or "provides
| support for exemplification") are common in man page short
| descriptions, they are not recommended for use in package
| synopses. For non-syntacticians the rule of thumb is that it
| should be possible to substitute the package name and synopsis
| into this formula:
|
| The package <name> provides {a,an,the,some} <synopsis>.
----------------------------------------------------------------------
Any suggestions? The most obvious thing that's missing from this is
justifications for the rules. I can see two arguments against verb
phrase descriptions.
First, verb phrase forms are split between two subtypes. On the one
hand there are the ones that imply the context "with this software
you'll be able to <do X>"; on the other there are the ones inflected
to fit a context like "this software <does X>". If we're going to
pick the commoner variant to standardise on, noun phrases beat both.
Second, man page short descriptions would only be a safe basis for
package short descriptions if every package delivered a single user
executable (and even then it would be a stretch to claim that
xeg_0.1-1_all.deb creates examples). For packages like libeg0 and
ttf-eg and eg-tools, the trouble with verb phrases is that they omit
the subject of the sentence, which leaves readers having to guess
what _kind_ of package it is - a daemon? A collection of command
line utilities? Or what?
But this is already a relatively long subsection...
APPENDIX
Round one: http://lists.debian.org/debian-l10n-english/2007/08/msg00000.html
Round two: http://lists.debian.org/debian-l10n-english/2008/08/msg00004.html
Leading to: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=516436
DevRef online: http://www.debian.org/doc/developers-reference/best-pkging-practices.html#bpp-pkg-synopsis
New bug: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=536889
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: