Re: Text improvements
Christian Perrier wrote:
Please note that the general choice has been using the US spelling
style (no real preference here....we just had to make a choice..:-)))
It was not the intention of my wording-check script to check US/GB
spelling, but as a side effect it logs some of the problems (see
Bug#315535).
The best is sending the patches package by package as bug reportsso
that bugs can be fixed one by one (most spelling errors do for
instance need special care to avoid fuzzying translations for no
reason)
I see. I hold back my changes now until I have a better understanding of
the workflow within d-i.
Some problems should be discussed, e.g. I would like to invent the
following:
Rule: Code quoting - code should be quoted using single quotes
Problem: Words are witten in different style, e.g.
(1) GRUB - follows the 'acronym rule'
(2) grub - follows the 'code (or computer interface) rule'
(3) 'grub' - same as (2) but quoted
(4) "grub" - double quoted
Examples (reported by script):
#Problem/word: [ GRUB ] in
/home/helmut/d-i/trunk/packages/arch/i386/grub-installer/debian/grub-installer.templates
line_no 4
# line: _Description: Install the GRUB boot loader to the master
boot record?
#Problem/word: [ GRUB ] in
/home/helmut/d-i/trunk/packages/arch/i386/grub-installer/debian/grub-installer.templates
line_no 29
# line: _Description: Install the GRUB bootloader to XFS file system?
#Problem/word: [ GRUB ] in
/home/helmut/d-i/trunk/packages/arch/i386/grub-installer/debian/grub-installer.templates
line_no 44
# line: - "(hd0)" or "/dev/hda" will install GRUB to the master
boot record of
#Problem/word: [ grub ] in
/home/helmut/d-i/trunk/packages/arch/i386/grub-installer/debian/grub-installer.templates
line_no 74
# line: The grub package failed to install into /target/.
Installing GRUB
#Problem/word: [ 'grub' ] in
/home/helmut/d-i/trunk/packages/arch/i386/grub-installer/debian/grub-installer.templates
line_no 102
# line: _Description: Installing the 'grub' package...
Applying the 'code quoting rule' will result in the following patches:
_Description: Install the GRUB boot loader to the master boot record?
-_Description: Install the GRUB bootloader to XFS file system?
+_Description: Install the GRUB boot loader to XFS file system?
- - "(hd0)" or "/dev/hda" will install GRUB to the master boot record
+ - '(hd0)' or '/dev/hda' will install GRUB to the master boot record
- The grub package failed to install into /target/. Installing GRUB
+ The 'grub' package failed to install into '/target/'. Installing GRUB
_Description: Installing the 'grub' package...
IMHO this would improve readability in many cases, a typical example is
s390-netdevice.templates line_no 60
| HiperSockets or an OSA-Express card in QDIO mode please use the qeth
where "... use 'qeth'" is better readable.
Don't forget doing so in your own language (I have assumed this is
German from your name).
You catched me;-)
Some teams have done such work but here also,
improvements are likely (however, for German, Jens Seidel and the
debian-l10n-german team already did a tremendous work).
I know.
But with a few hours per week it is IMHO better, to write some scripts,
which do most of the checks and changes. Proofreading the docu of a
small/medium package takes 1-4 hours, a review 10-40 hours, an accurate
docu versus code re-engineering ~100 hours. Doing all manually would
allow me only a few packages to improve _and_ re-review from time to time.
As I have a payed project of docu re-engineering a commercial package of
similar size, I can take d-i as a 'test-case' to see, how and if the
automation works at the level of good quality. Maybe I can make it
possible in some months to run such checks over ALL.debian.org.
Helmut Wollmersdorfer
Reply to: