Re: improving DevRef 6.2.2
Justin B Rye <jbr@edlug.org.uk> writes:
> 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".
[…]
> That second paragraph is where the trouble starts.
>
> First, valid package synopses aren't clauses. Clauses have verbs.
Is there a better, specific, term for what "red-nosed reindeer" is in
the phrase "Rudolph the red-nosed reindeer"?
> Second, ["appositive clause" isn't defined in WordNet and means
> something different in grammar dictionaries]
That's sufficient reason, I think, to stop using the term in the
context of the package synopsis.
> […] 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).
Do linguists have a standard term for such a thing then?
> 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.
Yes, this has been my main motivation in asking people to follow Dev
Ref §6.2.2. Nothing to do with superior language, but rather for
standardising the format to facilitate more reliable and flexible use
of synopses (as is the goal with most standardisation effort).
> 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.
Software developers do, though, have a tendency to want to know the
technical justification for a particular rule; this extends often to
rules of language. I think there's value in at least referring the
reader to a linguistic term that they can pursue to find out more.
> 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.
I se it as a reflexive explanation of the form from the desire that
the synopsis to fit the hypothetical §6.2.2 template "<packagename> is
<article> <synopsis>". I still find that desirable, and would like to
see it grammatically explained, even briefly.
> Okay, here's a delayed 6.2.2 revision draft 2a, which I'm posting to
> the list before I accidentally delete it again:
Thanks for this work.
> ---------------------------------------------------------------------
> | 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:
I'd find this easier to parse if it just listed the three articles as
"a, an, the".
> | libeg0 - exemplification support library
In a section discussing synopses, this "for instance" should show the
synopsis. Instead it confusingly shows the package name, when the
reader has already ben told not to repeat the package name.
Perhaps this would be better shown as two control fields:
Package: libeg0
Description: exemplification support library
…
Alternatively, the explanatory text could state what example package
name is being used, while showing only synopsis values for
illustration.
> | 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.
Again, this would be easier (for this sysadmin) to read if given as:
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:
> |
> | eg-tools - simple exemplification system (utilities)
This might be clearer if two illustrations were given for comparison:
Package: eg-tools
Description: simple exemplification system (utilities)
…
Package: eg-doc
Description: simple exemplification system (documentation)
…
> | These suite-and-role synopses need a modified formula:
> |
> | The package "$NAME" provides [a...] $ROLE for [a...] $SUITE
Unclear. Perhaps "These synopses follow an extended formula to the
simple one above. The synopsis of the package $NAME expressed as
'$SUITE ($ROLE)' can be described in a sentence such as 'The package
$NAME provides $ROLE for {a,an,the,some} $SUITE.'."
Glad to see this topic getting serious consideration.
--
\ “The greater the artist, the greater the doubt; perfect |
`\ confidence is granted to the less talented as a consolation |
_o__) prize.” —Robert Hughes |
Ben Finney
Reply to: