Re: improving DevRef 6.2.2
(I've been working on another attempt, attached at the end.)
Ben Finney wrote:
> Justin B Rye <jbr@edlug.org.uk> writes:
>> What we _could_ say is that they're appositive noun phrases EXCEPT
>> THAT they drop leading articles.
>
> Okay. If there's no simple term to unambiguously mark what we're
> describing, it's probably best to define what is meant in the
> document, without any non-standard linguistic terminology.
One point I haven't mentioned is that the standard terminology for
"noun phrase without an article" is "anarthrous NP", which is
thoroughly opaque! I'll try "disarticulated" (but avoid implying
it's official).
>> And this is why I didn't want to go blundering into debian-mentors
>> shouting "it's not an appositive clause!" - the advice I see being
>> given is good, it's only the rationale that's problematic.
>
> Jut as a point of interest, and possibly to play devil's advocate:
> *why* do we want the synopsis to not begin with an article ("a, an,
> the" etc.)? I have an impression that it's better, but I'd like to
> know if you can articulate why. In re-proposing this advice for the
> developer's reference, we're likely to meet with this question, so it
> would be good to have an explanation ready.
Short descriptions need to be easy to browse in package lists.
Compare the output of "cd /bin && whatis *" - a mix of different
sorts of noun and verb phrases; if there was a standard "template"
that all of them had to fit they'd be a lot more readable.
Why disarticulated NPs, particularly? Well, it's far too late to
switch to VPs, and disarticulated NPs are in a clear majority, so
that's the direction to push in. It also happens to save a few
display columns (and a few bytes per Packages entry) in a manner
that people are used to from other contexts, such as book-title
alphabeticisation schemes and journalese - it's not as extreme as
newspaper headlines, but it is a "note-form" convention.
>>> The package "$NAME" provides {a,an,the,some} $SYNOPSIS.
>>
>> (I'm still a bit unsure about including "some", though it does help
>> accommodate plural NPs.)
>
> The existing phrasing in §6.2.2 gives alternation for the copula:
> "{is, are}", presumably to allow for a synopsis in the plural. So the
> options so far presented still lead to awkwardness.
No, that's only intended to vary to allow for packages with
apparently singular or plural names ("eg-utils are", "eg-tool is");
it stays the same regardless of how the description is phrased
("...is/are a transition package for egtk").
And I prefer the idea that names of individual .deb files should
always be treated as singular, whether they're derived from a
singular noun phrase or a plural one. After all, there are also
some that started out as verb phrases: "suck", "createrepo",
"songwrite"... it's a bad idea for the template to pay any attention
to the internal structure of the name. It's always "eg-utils *is* a
Debian package".
But the verb I was using was "provides"...
> Given another example package:
>
> Package: eg-utils
> Description: utility programs for exemplification
>
> the options for a full sentence from this synopsis so far are:
>
> "The package eg-utils is some utility programs for exemplification."
>
> "The package eg-utils are the utility programs for exemplification."
The package are? Avoid equating foo.deb with /bin/foo and the
problem goes away:
"eg-utils provides a testing suite for libeg"
"eg-tool provides many libeg utilities (in one binary)"
Entirely natural either way.
>> Oh, and single quotes, I missed that.
>
> Perferably just as the Unicode characters themselves (‘’) in the
> document, rather than any fancy entity tricks to get them. (And
> definitely not apostrophes!)
The best-pkging-practices.dbk source uses plain ASCII-39 apostrophes
around 'Choices' (in 6.5.3), and that's the only example of quotes
in the text! Odd. Shouldn't it be some sort of <q>...</q>?
>> Oh, by the way - parentheses or dashes? I tend to like "($ROLE)",
>> but I think d-l-e has recommended "- $ROLE" in the past, and we
>> probably don't want to imply we're deprecating either.
>
> I think the de facto standard is the hyphen (as a stand-in for the en
> dash –), but I believe the grammatical contortions are less
> cumbersome if parentheses are used. Compare:
>
> "The package eg-tools is the simple exemplification system (utilities)."
>
> "The package eg-tools is the simple exemplification system – utilities."
>
> Perhaps a quick straw poll of the existing package synopses is
> appropriate, to see what the current majority practice is.
Tallying the 3600 packages installed on this Etch box, it's 224
instances of ' - ' versus 237 instances of final ')'; both of those
numbers include a lot of genuine instances of $ROLE, but brackets
are also pretty common for things like "(based on libpoppler)".
Latest draft (where *foo*=<replaceable>foo</replaceable> and "foo"
may end up as <quotation>foo</quotation>):
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
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 (disarticulated) noun phrase, 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*.
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:
Package: eg-tools
Description: simple exemplification system (utilities)
Package: eg-doc
Description: simple exemplification system (documentation)
These synopses follow a modified formula. Where a package "*name*"
has a synopsis "*suite* (*role*)" or "*suite* - *role*", the
elements should be phrased so that they fit into the formula:
The package *name* provides {a,an,the} *role* for the *suite*.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: