[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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: