Re: [RFR] dpo-tools manual
Judit Foglszinger wrote:
> for 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.
> [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.
>
> dpo-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.
>
> Visit https://www.arg.eti.br/blog/pages/software/dpo-tools/index.html for more
> information.
...in Portuguese.
>
> Obtaining 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.
> Remember to replace the number of the version in the following examples
> by the number of the last version of dpo-tools:
^^ ^^^^
s/by/with/, s/last/latest/
>
> 1. Download source code of dpo-tools:
1. Download dpo-tools:
> wget https://www.arg.eti.br/blog/pages/software/dpo-tools/dpo-tools_1.2.tgz
>
> 2. Decompress the file:
You're also de-archiving them here. Why is *this* stage, alone among
your example commands, being run verbosely?
> tar 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
> 3. Copy executable files to some directory in your PATH:
>
> cp 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...)
> Dependencies
>
> dpo-tools depend on other programs to function correctly.
^
s/depend/depends/
> You should have the following programs installed on your computer:
>
> gettext utilities: msgfmt, msgcat, msgmerge
> awk
> colordiff
>
> To install them in a Debian or debian-like systems:
^
Inconsistent capitalisation.
> sudo 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.
>
> You will want the podebconf-display-po too.
^^^
For once a surplus article. Why is this being done separately?
> To install it in your Debian or Debian-like system:
^^
You install software *on* a system.
> sudo 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.)
>
> README
>
> The following content is in the README file distributed with the dpo-tools source code.
This is worth providing a diff for.
>
> README
>
> 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
> should be done, they only try to use conventions used on the list debian-l10n-portuguese@lists.debian.org.
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-portuguese@lists.debian.org mailing list.
There should probably also be a warning here if the scripts are going
to be outputting messages in Portuguese.
>
> These are the scripts:
The scripts are:
(I assume these following are in a sort of "order of probable use".)
> dpo-get-templates: downloads a templates.pot file from podebconf templates repository.
^
Add "the". My diff also wraps and punctuates these lines
consistently.
> dpo-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.
> dpo-diff: presents informations in diff format, colorized and paginated
^
Information has no plural.
> dpo-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.
>
> Copy 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?
> dpo-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?
> the variable YEAR should be adjusted in the beginning of each year. You can
^^
s/in/at/.
> uncomment 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?)
>
> dpo-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?
> dpo-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.
> dpo-apply-compendium: set the COMPENDIUM variable to reflect the complete
> path of compendium file, downloaded from
^
> http://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?
> Uninstallation
>
> Just remove the scripts
Soon to become bad advice.
>
> Examples
>
> 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.
> the 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
^ ^
> podebconf file, breaks the lines of podebconf file in 80 column, verifies if the
^^
> podebconf file is well formated and tests the exibition of podebconf file:
^ ^^^^^^^^^ ^
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.
> $ 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.)
> $ vi package_pt_BR.po
Unconditionally advising innocent newbies to use vi is a crime against
humanity. On Debian you can always say
$ editor package_pt_BR.po
> $ 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
> with suggested changes:
>
> # replace "me" by your initials in the following commands
s/by/with/
> $ cp package_pt_BR.po package_pt_BR.me.po
> $ vi package_pt_BR.me.po
s/vi/editor/
> $ 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.
>
> 3. To apply a new version of templates file to a podebconf file already
^ ^^^^^^^
"The" templates file (I think).
> translated previously:
"Already previously" is redundant; drop the "already".
> $ dpo-get-templates pacote_pt_BR.po
> $ dpo-apply-templates pacote_pt_BR.po
s/pacote/package/g
>
> Author
>
> Written by Adriano Rafael Gomes (adrianorg@arg.eti.br)
>
> 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
README
dpo-tools is a set of shell scripts that can help with the translation
of Debian podebconf files. 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-portuguese@lists.debian.org mailing list.
The scripts are:
dpo-get-templates: downloads a templates.pot file from the podebconf
templates repository.
dpo-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 formatted.
dpo-diff: presents information in diff format, colorized and
paginated.
dpo-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.
Installation
Install the package, or copy the scripts to some directory in your
PATH.
Configuration
dpo-init-po.awk: set the variables NAME and EMAIL. If you are using
gawk, the variable YEAR should be adjusted at the beginning of each
year. You can uncomment the line which automatically detects the
year if your awk interpreter has support for the strftime()
function.
dpo-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
dpo-makepath: set the ID variable with an identifier such as your
initials.
dpo-apply-compendium: set the COMPENDIUM variable to reflect the
complete path of the compendium file downloaded from
https://i18n.debian.org/compendia/
Uninstallation
Uninstall the package, or just remove the scripts.
Examples
1. To begin a new translation:
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.
$ dpo-get-templates package
$ dpo-init-po package_version_templates.pot
$ dpo-apply-compendium package_pt_BR.po
$ editor package_pt_BR.po
$ 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 with suggested changes:
# replace "me" with your initials in the following commands
$ cp package_pt_BR.po package_pt_BR.me.po
$ editor package_pt_BR.me.po
$ 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
3. To apply a new version of the templates file to a podebconf file
translated previously:
$ dpo-get-templates package_pt_BR.po
$ dpo-apply-templates package_pt_BR.po
Author
Written by Adriano Rafael Gomes (adrianorg@arg.eti.br)
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.
--- dpo-tools-manual.txt 2018-09-07 00:39:26.646132615 +0100
+++ dpo-tools-manual.txt.jbr 2018-09-07 01:05:46.476276552 +0100
@@ -1,89 +1,98 @@
README
- 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
-should be done, they only try to use conventions used on the list debian-l10n-portuguese@lists.debian.org.
+ dpo-tools is a set of shell scripts that can help with the translation
+of Debian podebconf files. 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-portuguese@lists.debian.org mailing list.
- These are the scripts:
+ The scripts are:
- dpo-get-templates: downloads a templates.pot file from podebconf templates repository.
+ dpo-get-templates: downloads a templates.pot file from the podebconf
+ templates repository.
- dpo-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
+ dpo-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
+ translated from a compendium file.
- dpo-check: verifies if the podebconf file is well formated
+ dpo-check: verifies if the podebconf file is well formatted.
- dpo-diff: presents informations in diff format, colorized and paginated
+ dpo-diff: presents information in diff format, colorized and
+ paginated.
- dpo-make-patch: creates a patch file based on two versions of a podebconf
- file
+ dpo-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
+ dpo-wrap: breaks lines of a podebconf file to 80 columns.
-Instalation
+Installation
- Copy the scripts to some directory in your PATH
+ Install the package, or copy the scripts to some directory in your
+ PATH.
Configuration
- dpo-init-po.awk: set the variables NAME and EMAIL. If you are using gawk,
- the variable YEAR should be adjusted in the beginning of each year. You can
- uncomment the line which automatically detects the year, if your interpreter
- awk has support for strftime() function.
-
- dpo-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
-
- dpo-makepath: set the ID variable with the initials of your name.
-
- dpo-apply-compendium: set the COMPENDIUM variable to reflect the complete
- path of compendium file, downloaded from
- http://i18n.debian.org/compendia/pt_BR/
+ dpo-init-po.awk: set the variables NAME and EMAIL. If you are using
+ gawk, the variable YEAR should be adjusted at the beginning of each
+ year. You can uncomment the line which automatically detects the
+ year if your awk interpreter has support for the strftime()
+ function.
+
+ dpo-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
+
+ dpo-makepath: set the ID variable with an identifier such as your
+ initials.
+
+ dpo-apply-compendium: set the COMPENDIUM variable to reflect the
+ complete path of the compendium file downloaded from
+ https://i18n.debian.org/compendia/
Uninstallation
- Just remove the scripts
+ Uninstall the package, or just remove the scripts.
Examples
- 1. To initiate a new translation: the following sequence of commands does
-the 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
-podebconf file, breaks the lines of podebconf file in 80 column, verifies if the
-podebconf file is well formated and tests the exibition of podebconf file:
+ 1. To begin a new translation:
+
+ 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.
$ dpo-get-templates package
$ dpo-init-po package_version_templates.pot
$ dpo-apply-compendium package_pt_BR.po
- $ vi package_pt_BR.po
+ $ editor package_pt_BR.po
$ 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
- with suggested changes:
+ 2. To review a translation done by another translator and generate
+ a patch with suggested changes:
- # replace "me" by your initials in the following commands
+ # replace "me" with your initials in the following commands
$ cp package_pt_BR.po package_pt_BR.me.po
- $ vi package_pt_BR.me.po
+ $ editor package_pt_BR.me.po
$ 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)
+ $ # send the generated patch, answering the RFR
- 3. To apply a new version of templates file to a podebconf file already
+ 3. To apply a new version of the templates file to a podebconf file
translated previously:
- $ dpo-get-templates pacote_pt_BR.po
- $ dpo-apply-templates pacote_pt_BR.po
+ $ dpo-get-templates package_pt_BR.po
+ $ dpo-apply-templates package_pt_BR.po
Author
Reply to: