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

Re: improving DevRef 6.2.2

Second draft:
 Policy says that the synopsis line (the short description) needs to
 be informative but concise, and must not repeat the package's name.

 The synopsis functions as an appositive phrase describing the
 package. Since it isn't a complete sentence, sentential punctuation
 is inappropriate: it does not need initial capitalization or a
 final period (full stop). It should also omit any initial article,
 either definite ("the") or indefinite ("a" or "an").
 A good rule of thumb is that it should be possible to substitute
 the packagename and synopsis into the formula:

	The package "$NAME" provides [a(n)|the|some] $SYNOPSIS.

 One valid exception is that families of packages may use a scheme
 that divides the synopsis into two parts. In this case the first
 part is a description of the whole family and the second summarises
 the package's role within it:

	kopher-data - KDE gopher client (icons)
	libkopher0  - KDE gopher client (libraries)

 These "- FAMILY (ROLE)" synopses need a modified rule of thumb:

	The package "$NAME" provides [a...] $ROLE for [a...] $FAMILY


Some unobjectionable examples of this format:

alsaplayer-text - PCM player designed for ALSA (text version)
libjack0.100.0-0 - JACK Audio Connection Kit (libraries)
xemacs21-nomule - highly customizable text editor -- Non-mule binary

I don't see any need for these to be outlawed, so I'm just trying to
find a good concise way of describing them.
Ankh kak! (Ancient Egyptian blessing)

Reply to: