Hello all
I start a project to translate the package descritions and write the
'ddts' (Debian Descriptions Translation Server) with a mail interface.
Now we have -de and some -pt_BR translation in the database.
for more information see: http://auric.debian.org/~grisu/ddts/
With this I have see a lot of package descriptions in the last weeks.
English and translated description and I found (maybe) some bad
descriptions.
I search and found some policy about the descriptions in "Debian New
Maintainers' Guide (1.0)" section 4.1 [1], in "Debian Policy Manual
(3.5.6.0)" section 5.7 [2] and in "Debian Packaging Manual (3.1.1.1)"
section 7. [3].
The description should/may/must:
1. the short description shouldn't be longer than about 60
characters [1]
2. should be kept brief - certainly under 80 characters. [2]
3. Do not include the package name in the synopsis line [2]
4. Do not try to continue the single line synopsis into the extended
description [2]
5. in the long description:
5.a There must be no blank lines [1]
5.b " ." at the beginning make a blank line [1]
5.c Do not use tab characters [2] [3]
5.d Every package should also have an extended description. [3]
5.e starting with a single space are part of a paragraph. Successive
lines of this form will be word-wrapped when displayed. [3]
5.f Lines starting with two or more spaces will be displayed
verbatim. [3]
5.g lines containing a single space followed by a single full stop
character, will are rendered as blank lines. [3]
5.h lines containing a space, a full stop and some more characters,
are for future expansion. Do not use them. [3]
5.i _Always_ start extended description lines with at least one
whitespace character. [3]
(maybe we should concentrate all rules in one policy and make links to this in
the others.)
I have collect some examples of bad descriptions:
|bad:
| You just have to place the package files into a incoming
| directory and the tool does the sorting (if you place the
| .changes file there too).
|better:
| You just have to place the package files into a incoming
| directory and the tool does the sorting (if you place
| the .changes file there too).
(see 5.h)
|bad:
|Description: a rich collection of X11 Greek fonts
| This collection includes 100dpi/75dpi/misc(fixed,etc) and
| Type1 (Postscript) fonts for use in X11, that adhere to the
| standard ISO8859-7 (ELOT-928) standard encoding. Some fonts
| exist also in codepage 737 encoding (traditional greek DOS
| encoding) which can be used (with rxvt) for typing 737 greek.
| The fonts were created by Thanassis Protopapas <protopap@cog.brown.edu> and
| Angelo Haritsis <ah@doc.ic.ac.uk>. Some fonts were modified by Yiannis
| Giftomitros <yang@hellug.gr>.
|better:
|Description: a rich collection of X11 Greek fonts
| This collection includes 100dpi/75dpi/misc(fixed,etc) and
| Type1 (Postscript) fonts for use in X11, that adhere to the
| standard ISO8859-7 (ELOT-928) standard encoding. Some fonts
| exist also in codepage 737 encoding (traditional greek DOS
| encoding) which can be used (with rxvt) for typing 737 greek.
| .
| The fonts were created by Thanassis Protopapas <protopap@cog.brown.edu> and
| Angelo Haritsis <ah@doc.ic.ac.uk>. Some fonts were modified by Yiannis
| Giftomitros <yang@hellug.gr>.
(see 5.e, 5.f)
|bad:
|Description: Some DVI utilities
| This package includes following commands.
| dviselect: Dviselect selects pages from a DVI file, creating a new DVI file.
| The package xdvik-ja uses dviselect for printing out a piece of
| the DVI file.
| dviconcat: Dviconcat concatenates DVI files.
|better:
|Description: Some DVI utilities
| This package includes following commands.
| dviselect: Dviselect selects pages from a DVI file, creating a new DVI file.
| The package xdvik-ja uses dviselect for printing out a piece of
| the DVI file.
| dviconcat: Dviconcat concatenates DVI files.
(see 5.f)
|bad:
| o Adduser can create new users and groups and add existing users to
| existing groups.
| o Deluser can remove users and groups and remove users from specific
| groups.
|better:
| o Adduser can create new users and groups and add existing users to
| existing groups.
| o Deluser can remove users and groups and remove users from specific
| groups.
(see 5.f)
I have some questions:
- can we write bugreports about this?
- can someone write a lintian warning for 5.h ?
The next one are not 'real' bugs, but the first I don't understand and the last
make the translation easier.
|bad:
|Description: An utility for creating fonts.scale file for TTF fonts.
| .
| ''This program is for users of xfsft by Juliusz Chroboczek
| and Mark Leisher. It reads TrueType fonts and creates a
|besster:
|Description: An utility for creating fonts.scale file for TTF fonts.
| ''This program is for users of xfsft by Juliusz Chroboczek
| and Mark Leisher. It reads TrueType fonts and creates a
is the extra blank line on the top of the description usefull?
|bad:
| Console Tool Kit is a toolkit for writing textbased GUIs. The syntax is
| almost the same as GTK+. It provides mouse support on the console through
| gpm.
| This package is for developing with the latest ctk.
|better:
| Console Tool Kit is a toolkit for writing textbased GUIs. The syntax is
| almost the same as GTK+. It provides mouse support on the console through
| gpm.
| .
| This package is for developing with the latest ctk.
We have a lot -dev packages with the same description of the nodev package.
This extra paragraph (6.e) make the description more clear and the translation
is easier.
Gruss
Grisu
--
Michael Bramer - a Debian Linux Developer http://www.debian.org
PGP: finger grisu@db.debian.org -- Linux Sysadmin -- Use Debian Linux
The UNIX Guru's view of Sex: unzip ; strip ; touch ; finger ;
mount ; fsck ; more ; yes ; umount ; sleep
Attachment:
pgpEkp2ZM1J7R.pgp
Description: PGP signature