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