--- Begin Message ---
- To: Debian Bug Tracking System <submit@bugs.debian.org>
- Subject: 6.2.2: talks nonsense about "appositive clauses"
- From: Justin B Rye <jbr@edlug.org.uk>
- Date: Sat, 21 Feb 2009 12:51:57 +0000
- Message-id: <20090221125157.GA30205@xibalba.demon.co.uk>
Package: developers-reference
Version: 3.4.1
Severity: normal
Tags: patch
This report has been brewing on debian-l10n-english for years - see
"http://lists.debian.org/debian-l10n-english/2008/08/msg00004.html";
The advice in DevRef 6.2.2 about package short descriptions is good,
but it's undermined by the fact that the rationale given is hogwash.
For a start:
# An appositive clause is defined in WordNet as a grammatical
# relation between a word and a noun phrase
Alas, valid package synopses are _not_ appositive clauses (indeed,
they're neither appositive nor clauses); clauses are not grammatical
relations; and what's more, WordNet has no such entry.
Now, the use of this kind of pseudoscientific gobbledygook in
justification for a rule may offend me as a linguistics graduate,
but that doesn't mean I want to see it replaced with an accurate
version. Even if every word of it was true, it would still be a bad
idea to base policy guidelines on a set of formal syntactic
principles, since most Debian package maintainers have had no
particular training in English syntactic analysis.
Besides, the grammatical rules clearly aren't the real reason for
the rule. If we're going to justify our advice, we should explain
it in terms of the real benefits it brings, such as that
standardising makes it easier for users to browse through a list of
short descriptions.
My patch concentrates on providing templates that developers can fit
their proposed synopses into. If you're interested in thrashing out
details of the wording, now would be a good time to bring it back to
debian-l10n-english@lists.debian.org, since there are more posters
around than usual.
--
JBR Uqarituukasippungaasiit (one word in West Greenlandic)
"Silly me, I went and spoke out of turn as usual!"
diff -ru ../developers-reference-3.4.0.pristine/best-pkging-practices.dbk ./best-pkging-practices.dbk
--- ../developers-reference-3.4.0.pristine/best-pkging-practices.dbk 2008-06-02 11:29:07.000000000 +0100
+++ ./best-pkging-practices.dbk 2009-02-20 20:53:11.000000000 +0000
@@ -210,41 +210,50 @@
<section id="bpp-pkg-synopsis">
<title>The package synopsis, or short description</title>
<para>
-The synopsis line (the short description) should be concise. It must not
-repeat the package's name (this is policy).
+Policy says the synopsis line (the short description) must be concise, not
+repeating the package name, but also informative.
</para>
<para>
-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. 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). It should also not
-begin with an article, either definite (the) or indefinite (a or an).
-</para>
-<para>
-It might help to imagine that the synopsis is combined with the package name in
-the following way:
+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:
</para>
<screen>
-<replaceable>package-name</replaceable> is a <replaceable>synopsis</replaceable>.
+Package: libeg0
+Description: exemplification support library
</screen>
<para>
-Alternatively, it might make sense to think of it as
+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:
</para>
-<screen>
-<replaceable>package-name</replaceable> is <replaceable>synopsis</replaceable>.
-</screen>
<para>
-or, if the package name itself is a plural (such as developers-tools)
+The package <replaceable>name</replaceable> provides {a,an,the,some}
+<replaceable>synopsis</replaceable>.
+</para>
+<para>
+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:
</para>
<screen>
-<replaceable>package-name</replaceable> are <replaceable>synopsis</replaceable>.
+Package: eg-tools
+Description: simple exemplification system (utilities)
+
+Package: eg-doc
+Description: simple exemplification system - documentation
</screen>
<para>
-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.
+These synopses follow a modified formula. Where a package
+"<replaceable>name</replaceable>" has a synopsis
+"<replaceable>suite</replaceable> (<replaceable>role</replaceable>)" or
+"<replaceable>suite</replaceable> - <replaceable>role</replaceable>", the
+elements should be phrased so that they fit into the formula:
+</para>
+<para>
+The package <replaceable>name</replaceable> provides {a,an,the}
+<replaceable>role</replaceable> for the <replaceable>suite</replaceable>.
</para>
</section>
--- End Message ---
--- Begin Message ---
Source: developers-reference
Source-Version: 3.4.2
We believe that the bug you reported is fixed in the latest version of
developers-reference, which is due to be installed in the Debian FTP archive:
developers-reference-fr_3.4.2_all.deb
to pool/main/d/developers-reference/developers-reference-fr_3.4.2_all.deb
developers-reference_3.4.2.dsc
to pool/main/d/developers-reference/developers-reference_3.4.2.dsc
developers-reference_3.4.2.tar.gz
to pool/main/d/developers-reference/developers-reference_3.4.2.tar.gz
developers-reference_3.4.2_all.deb
to pool/main/d/developers-reference/developers-reference_3.4.2_all.deb
A summary of the changes between this version and the previous one is
attached.
Thank you for reporting the bug, which will now be closed. If you
have further comments please address them to 516436@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.
Debian distribution maintenance software
pp.
Lucas Nussbaum <lucas@lucas-nussbaum.net> (supplier of updated developers-reference package)
(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Format: 1.8
Date: Sat, 22 Aug 2009 12:28:04 +0200
Source: developers-reference
Binary: developers-reference developers-reference-fr
Architecture: source all
Version: 3.4.2
Distribution: unstable
Urgency: low
Maintainer: Debian Documentation Project <debian-doc@lists.debian.org>
Changed-By: Lucas Nussbaum <lucas@lucas-nussbaum.net>
Description:
developers-reference - guidelines and information for Debian developers
developers-reference-fr - guidelines and information for Debian developers, in French
Closes: 516375 516436 523985 525668 526410 527008 532945 534688 538245
Changes:
developers-reference (3.4.2) unstable; urgency=low
.
* Applied patch from Justin B Rye that improves the discussion on writing
package descriptions. Closes: #516436.
* Lenny has been released, update the list of codenames. Closes: #527008.
* Applied patch from Paul Wise that adds a paragraph about hostile
upstreams. Closes: #523985.
* Applied patch from Charles Plessy about providing information to the
ftpmasters. Closes: #526410.
* In the section about patch systems, mention quilt (wasn not
mentionned before) and describe it as the recommended patch system.
also mention dpatch and cdbs' patch system. drop dbs. Closes: #525668.
* Added a note in the wanna-build section to mention
http://release.debian.org/wanna-build.txt. Closes: #516375.
* Clarified NMU versioning to reflect existing practices. Closes: #532945.
* s/README.Debian-source/README.source/ in the section
about repackaged upstream tarballs.
* Mention the Gandi.net hosting discount in section 4.13.
Applied patch from Tim Retout. Closes: #538245.
* Reduce length of title of L10N section so that it is no longer split.
Applied patch from Justin B Rye. Closes: #534688.
* Bumped debhelper compat level to 5 (4 was deprecated)
* Bump Standards-Version to 3.8.2. No changes needed.
* Added pointer to debian-project@ post about the wanna-build team.
Checksums-Sha1:
57e7756559341a417e0269ddec3534e045f3f79e 1187 developers-reference_3.4.2.dsc
a859135d2368dc10c401de76db0395af9551098b 510265 developers-reference_3.4.2.tar.gz
4d7f104ce6a40345eab0184e7d419b2645237cee 691638 developers-reference_3.4.2_all.deb
76b37386f444e18b615ce0a3573affa0552faa97 707296 developers-reference-fr_3.4.2_all.deb
Checksums-Sha256:
72064019736e2e6e64b348c7f7ce7c3407e45d471a0949394749f0280042cc08 1187 developers-reference_3.4.2.dsc
d4767fe14504bb5405ccc67aaeb6c52d696326177bdc08ac1668ae7d339b4d22 510265 developers-reference_3.4.2.tar.gz
d9d15cfcb22bcfe169b23db55be0af5f2e8d16bf1047f4adb1eb34edaa68423b 691638 developers-reference_3.4.2_all.deb
49b2e0c624ae0887e298068eb7fb9e986bbc0286210696eb73dd272cb5d6e632 707296 developers-reference-fr_3.4.2_all.deb
Files:
b820d97af745c7d571128bfe138b3dff 1187 doc optional developers-reference_3.4.2.dsc
ea1dd6cd7c85d95e41d951e442866439 510265 doc optional developers-reference_3.4.2.tar.gz
a9dc7900ec7c3f4016a7576d9e0ec853 691638 doc optional developers-reference_3.4.2_all.deb
c9500b5fcece290b9f3c63aefe138cc2 707296 doc optional developers-reference-fr_3.4.2_all.deb
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
iD8DBQFKj8072hliNwI7P08RAkOKAKC4N28+UAJsTRSc/Yip9CXTcMGiJQCeMS5/
4iJRiG11xGx0j6jlpySIWuM=
=Ekkg
-----END PGP SIGNATURE-----
--- End Message ---