Post by Judit Foglszingerfor a package from a portugese upstream (dpo-tools) [1],
documentation got translated to English.
Now, I'm asking for review, if the English is sane.
It definitely needs some work.
Post by Judit Foglszinger[1] https://www.arg.eti.br/blog/pages/software/dpo-tools/index.html
Dpo-Tools user manual
This file is useless. It's a short description of the software
(information which should be available via the package description
even if I haven't installed it) plus bad advice about how to install
it. But here's a review of the English anyway.
Post by Judit Foglszingerdpo-tools is set of shell scripts that can help you in translation of Debian podebconf files.
^
Missing article: "a set". The rest of the sentence is just subtly
unidiomatic. I'd go for
dpo-tools is a set of shell scripts that can help with the translation of Debian podebconf files.
or
dpo-tools is a set of shell scripts useful for translating Debian podebconf files.
By the way, shellcheck says these scripts are badly in need of some
extra quoting.
Post by Judit FoglszingerVisit https://www.arg.eti.br/blog/pages/software/dpo-tools/index.html for more
information.
...in Portuguese.
Post by Judit FoglszingerObtaining dpo-tools
To obtain dpo-tools, visit https://www.arg.eti.br/blog/pages/software
/dpo-tools/index.html and download a copy of the source code.
^^^^^^
It isn't source for a compiler, it's just a set of scripts. Make it:
and download a copy.
Post by Judit FoglszingerRemember to replace the number of the version in the following examples
^^ ^^^^
s/by/with/, s/last/latest/
Post by Judit Foglszingerwget https://www.arg.eti.br/blog/pages/software/dpo-tools/dpo-tools_1.2.tgz
You're also de-archiving them here. Why is *this* stage, alone among
your example commands, being run verbosely?
Post by Judit Foglszingertar zxvf dpo-tools_1.2.tgz
You wouldn't need to say the thing above about replacing version
numbers if this said
tar xzf dpo-tools_*.tgz
Post by Judit Foglszingercp dpo-* ~/bin/ or sudo cp dpo-* /usr/local/bin/
(Depending on your umask, that latter may create them unreadable
and/or nonexecutable for non-root...)
Post by Judit FoglszingerDependencies
dpo-tools depend on other programs to function correctly.
^
s/depend/depends/
Post by Judit Foglszingergettext utilities: msgfmt, msgcat, msgmerge
awk
colordiff
^
Inconsistent capitalisation.
Post by Judit Foglszingersudo aptitude install gettext gawk colordiff
If all that's needed is some implementation of awk, you don't need to
install gawk; base-files (Priority: required) already Pre-Depends on
something providing the awk virtual package. Oh, and technically you
might not have either sudo or aptitude installed.
Post by Judit FoglszingerYou will want the podebconf-display-po too.
^^^
For once a surplus article. Why is this being done separately?
^^
You install software *on* a system.
Post by Judit Foglszingersudo aptitude install po-debconf
If you were going to end by installing po-debconf then it was a waste
of effort to manually install gettext, since of course po-debconf
depends on gettext. This whole Dependencies section could just say:
sudo apt install colordiff po-debconf
(And that's besides the fact that it all becomes redundant once the
software is itself in Debian.)
Post by Judit FoglszingerREADME
The following content is in the README file distributed with the dpo-tools source code.
This is worth providing a diff for.
Post by Judit FoglszingerREADME
dpo-tools is set of shell scripts that can help you in translation of Debian
podebconf files. Dpo-tools do not force any rules of how translations
First sentence, again:
dpo-tools is a set of shell scripts that can help with the
translation of Debian podebconf files.
or
dpo-tools is a set of shell scripts useful for translating Debian
podebconf files.
Second sentence:
It does not enforce any rules about how translations should be done;
it only tries to abide by the conventions used on the
debian-l10n-***@lists.debian.org mailing list.
There should probably also be a warning here if the scripts are going
to be outputting messages in Portuguese.
The scripts are:
(I assume these following are in a sort of "order of probable use".)
Post by Judit Foglszingerdpo-get-templates: downloads a templates.pot file from podebconf templates repository.
^
Add "the". My diff also wraps and punctuates these lines
consistently.
Post by Judit Foglszingerdpo-init-po: creates and initializes a podebconf file from a templates file.
dpo-apply-templates: updates a debconf file with a new version of your
templates file.
dpo-apply-compendium: updates a podebconf file with strings already
translated from a compendium file
dpo-check: verifies if the podebconf file is well formated
^
Spelling: formatted.
Post by Judit Foglszingerdpo-diff: presents informations in diff format, colorized and paginated
^
Information has no plural.
Post by Judit Foglszingerdpo-make-patch: creates a patch file based on two versions of a podebconf
file
dpo-wrap: breaks lines of a podebconf file to 80 columns
Instalation
^
Spelling: Installation. Again, the following will soon be bad advice.
Post by Judit FoglszingerCopy the scripts to some directory in your PATH
Configuration
What files is this talking about? Where do they live? Do Debian
users in fact need to do any of this?
Post by Judit Foglszingerdpo-init-po.awk: set the variables NAME and EMAIL. If you are using gawk,
What should I do if I'm using mawk or original-awk?
Post by Judit Foglszingerthe variable YEAR should be adjusted in the beginning of each year. You can
^^
s/in/at/.
Post by Judit Foglszingeruncomment the line which automatically detects the year, if your interpreter
awk has support for strftime() function.
Should be "if your awk interpreter has support for the strftime()
function". But how are readers supposed to know whether or not this
is the case? (And if gawk *doesn't* support this easier approach, why
was gawk the implementation recommended above?)
Post by Judit Foglszingerdpo-init.po: edit the last line of the file to reflect the complete path of
the file dpo-init.po.awk. Example: ~/bin/dpo-init-po.awk
Wait, what? Is it a config file or an executable?
Post by Judit Foglszingerdpo-makepath: set the ID variable with the initials of your name.
This shouldn't be presented as a strict rule; if there's already
somebody active on the mailinglist with the same initials you'd be
better off using your username. (Indeed, making that the standard
convention would obviously make it easier to automate.) I would
suggest saying:
dpo-makepath: set the ID variable with an identifier such as your
initials.
Post by Judit Foglszingerdpo-apply-compendium: set the COMPENDIUM variable to reflect the complete
path of compendium file, downloaded from
^
Post by Judit Foglszingerhttp://i18n.debian.org/compendia/pt_BR/
^
Missing article yet again, s/http/https/, and don't assume that the
one I'm interested in is pt_BR. Wait, when did anybody download that?
Post by Judit FoglszingerUninstallation
Just remove the scripts
Soon to become bad advice.
Post by Judit FoglszingerExamples
1. To initiate a new translation: the following sequence of commands does
s/initiate/begin/
Misused colon; I would suggest making the rest of this sentence into a
separate paragraph.
Post by Judit Foglszingerthe download of a podebconf templates file, creates a podebconf file based on
the downloaded templates file, initializes the podebconf file with commonly used
informations, updates the podebconf file with strings from compendium, edits the
^ ^
Post by Judit Foglszingerpodebconf file, breaks the lines of podebconf file in 80 column, verifies if the
^^
^ ^^^^^^^^^ ^
Eliminating some repetition, I would suggest:
The following sequence of commands downloads a podebconf templates
file, creates a podebconf file based on that file, initializes the
podebconf file with commonly used information, updates it with
strings from the compendium for Brazilian Portuguese, edits it,
imposes 80-column lines, validates its format, and displays the
resulting podebconf file.
Post by Judit Foglszinger$ dpo-get-templates package
$ dpo-init-po package_version_templates.pot
$ dpo-apply-compendium package_pt_BR.po
(I've added a mention above that this is assuming pt_BR.)
Unconditionally advising innocent newbies to use vi is a crime against
humanity. On Debian you can always say
$ editor package_pt_BR.po
Post by Judit Foglszinger$ dpo-wrap package_pt_BR.po
$ dpo-check package_pt_BR.po
$ podebconf-display-po package_pt_BR.po
$ # send the file package_pt_BR.po to RFR (request for review)
2. To review a translation done by another translator and generate a patch
# replace "me" by your initials in the following commands
s/by/with/
Post by Judit Foglszinger$ cp package_pt_BR.po package_pt_BR.me.po
$ vi package_pt_BR.me.po
s/vi/editor/
Post by Judit Foglszinger$ dpo-wrap package_pt_BR.me.po
$ dpo-check package_pt_BR.me.po
$ podebconf-display-po package_pt_BR.me.po
$ dpo-make-patch package_pt_BR.po
$ # send the generated patch, answering the RFR (request for review)
You've already expanded RFR.
Post by Judit Foglszinger3. To apply a new version of templates file to a podebconf file already
^ ^^^^^^^
"The" templates file (I think).
"Already previously" is redundant; drop the "already".
Post by Judit Foglszinger$ dpo-get-templates pacote_pt_BR.po
$ dpo-apply-templates pacote_pt_BR.po
s/pacote/package/g
Post by Judit FoglszingerAuthor
Copyright
Copyright (C) 2008,2012 Adriano Rafael Gomes.
GPLv3+ License: GNU GPL version 3 or newer http://gnu.org/licenses/gpl.html.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package