[Po4a-devel]Minor documentation review
Danilo Piazzalunga
danilopiazza@libero.it
Mon, 14 Feb 2005 15:24:18 +0100
--Boundary-00=_SSLECyVSdTTXR2S
Content-Type: text/plain;
charset="us-ascii"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline
Hello,
While reading the documentation to translate it, I've found some spelling
errors, typos, and such minor errors. At last, the time has come to submit
this.
A summary of the proposed changes follows:
* Fix some (mostly cosmetic) typos, without changing the meaning of
anything. For example:
- Change case, e.g. s/french/French/.
- Use consistently 'addenda' as the plural form for 'addendum'.
- s/somehow/somewhat/ when the meaning is 'rather', 'to some degree' and
not 'for some reason'.
- Fix some spelling errors, like s/formating/formatting/ and
s/dupplicate/duplicate/.
If any changes are approved and if everybody agrees, I will also (try to) take
care string unfuzzyfication.
Cheers,
Danilo
--
Danilo Piazzalunga +--------------------+
PGP Key available at subkeys.pgp.net | Linux User #245762 |
Fingerprint: D018 815E 8C7F 2AE2 5565 | ICQ #105550412 |
0C36 B5F6 DB20 B800 CB9F +--------------------+
--Boundary-00=_SSLECyVSdTTXR2S
Content-Type: text/plain;
charset="us-ascii";
name="po4a-docreview.diff"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename="po4a-docreview.diff"
[Danilo Piazzalunga]
(documentation)
* Fix some (mostly cosmetic) typos, without changing the meaning of
anything. For example:
- Change case, e.g. s/french/French/.
- Use consistently 'addenda' as the plural form for 'addendum'.
- s/somehow/somewhat/ when the meaning is 'rather', 'to some degree' and
not 'for some reason'.
- Fix some spelling errors, like s/formating/formatting/ and
s/dupplicate/duplicate/.
* TODO: string unfuzzyfication (let's be friendly to fellow translators).
Index: po4a
===================================================================
RCS file: /cvsroot/po4a/po4a/po4a,v
retrieving revision 1.22
diff -u -r1.22 po4a
--- po4a 11 Feb 2005 10:18:21 -0000 1.22
+++ po4a 14 Feb 2005 13:31:42 -0000
@@ -14,7 +14,7 @@
=head1 NAME
-po4a - Update both the po files and translated documents in one shot
+po4a - update both the po files and translated documents in one shot
=head1 SYNOPSIS
@@ -87,8 +87,8 @@
add_fr:doc/l10n/script.fr.add
This should be rather self-explanatory also. Note that in the second case,
-doc/l10n/script.fr.add is an addendum to add to the french version of this document.
-Please refer to po4a(7) for more information about the addendums.
+doc/l10n/script.fr.add is an addendum to add to the French version of this document.
+Please refer to po4a(7) for more information about the addenda.
More formally, the format is:
@@ -99,7 +99,7 @@
[type: pod] script $lang:doc/$lang/script.1 add_fr:doc/l10n/script.fr.add
-If all the languages had addendums with similar paths, you could also write
+If all the languages had addenda with similar paths, you could also write
something like:
[type: pod] script $lang:doc/$lang/script.1 add_$lang:doc/l10n/script.$lang.add
@@ -132,7 +132,8 @@
=item -A, --addendum-charset
-Charset of the addenda. Note that all addenda should be in the same charset.
+Charset of the addenda. Note that all the addenda should be in the same
+charset.
=item -V, --version
@@ -152,7 +153,7 @@
=back
-=head1 SHORTCOMING
+=head1 SHORTCOMINGS
=over 4
Index: po4a-gettextize
===================================================================
RCS file: /cvsroot/po4a/po4a/po4a-gettextize,v
retrieving revision 1.26
diff -u -r1.26 po4a-gettextize
--- po4a-gettextize 5 Feb 2005 13:03:22 -0000 1.26
+++ po4a-gettextize 14 Feb 2005 13:31:42 -0000
@@ -14,7 +14,7 @@
=head1 NAME
-po4a-gettextize - Convert an original file (and its translation) to a po file
+po4a-gettextize - convert an original file (and its translation) to a po file
=head1 SYNOPSIS
Index: po4a-normalize
===================================================================
RCS file: /cvsroot/po4a/po4a/po4a-normalize,v
retrieving revision 1.20
diff -u -r1.20 po4a-normalize
--- po4a-normalize 5 Feb 2005 13:03:22 -0000 1.20
+++ po4a-normalize 14 Feb 2005 13:31:42 -0000
@@ -14,7 +14,7 @@
=head1 NAME
-po4a-normalize - Normalize a documentation file by parsing it in po4a, and writing it back
+po4a-normalize - normalize a documentation file by parsing it in po4a, and writing it back
=head1 SYNOPSIS
Index: po4a-translate
===================================================================
RCS file: /cvsroot/po4a/po4a/po4a-translate,v
retrieving revision 1.32
diff -u -r1.32 po4a-translate
--- po4a-translate 5 Feb 2005 13:03:22 -0000 1.32
+++ po4a-translate 14 Feb 2005 13:31:43 -0000
@@ -14,7 +14,7 @@
=head1 NAME
-po4a-translate - convert back po file to documentation format.
+po4a-translate - convert a po file back to documentation format
=head1 SYNOPSIS
@@ -51,7 +51,8 @@
=item -A, --addendum-charset
-Charset of the addenda. Note that all addenda should be in the same charset.
+Charset of the addenda. Note that all the addenda should be in the same
+charset.
=item -m, --master
Index: po4a-updatepo
===================================================================
RCS file: /cvsroot/po4a/po4a/po4a-updatepo,v
retrieving revision 1.29
diff -u -r1.29 po4a-updatepo
--- po4a-updatepo 5 Feb 2005 13:03:22 -0000 1.29
+++ po4a-updatepo 14 Feb 2005 13:31:43 -0000
@@ -14,7 +14,7 @@
=head1 NAME
-po4a-updatepo - Update the translation (in po format) of documentation.
+po4a-updatepo - update the translation (in po format) of documentation
=head1 SYNOPSIS
Index: doc/po4a.7.pod
===================================================================
RCS file: /cvsroot/po4a/po4a/doc/po4a.7.pod,v
retrieving revision 1.33
diff -u -r1.33 po4a.7.pod
--- doc/po4a.7.pod 7 Jan 2005 22:50:51 -0000 1.33
+++ doc/po4a.7.pod 14 Feb 2005 13:31:44 -0000
@@ -91,16 +91,16 @@
I like the idea of open-source software, making it possible for everybody to
access to software and to their source code. But being French, I'm well
aware that the licensing is not the only restriction to the openness of
-software: Non-translated free softwares are useless for non-English
-speakers, and we still have some work to make them available to really
+software: non-translated free software is useless for non-English
+speakers, and we still have some work to make it available to really
everybody out there.
The perception of this situation by the open-source actors did dramatically
-improved recently. We, as translators, won the first battle and convinced
+improve recently. We, as translators, won the first battle and convinced
everybody of the translations' importance. But unfortunately, it was the easy
part. Now, we have to do the job and actually translate all this stuff.
-Actually, the open-source software themselves benefit of a rather decent
+Actually, open-source software themselves benefit of a rather decent
level of translation, thanks to the wonderful gettext tool suite. It is able
to extract the strings to translate from the program, present a uniform
format to translators, and then use the result of their works at run time to
@@ -108,7 +108,7 @@
But the situation is rather different when it comes to documentation. Too
often, the translated documentation is not visible enough (not distributed
-as a part of the program), only partial or, not up to date. This last
+as a part of the program), only partial, or not up to date. This last
situation is by far the worst possible one. Outdated translation can reveal
worse than no translation at all to the users by describing old program
behavior which are not in use anymore.
@@ -154,7 +154,7 @@
=head3 nroff
The good old manual pages' format, used by so much programs out there. The
-po4a support is very welcome here since this format is somehow difficult to
+po4a support is very welcome here since this format is somewhat difficult to
use and not really friendly to the newbies.
=head3 pod
@@ -167,7 +167,7 @@
=head3 sgml
-Even if somehow superseded by XML nowadays, this format is still used
+Even if somewhat superseded by XML nowadays, this format is still used
rather often for documents which are more than a few screens long. It allows
you to make complete books. Updating the translation of so long documents can
reveal to be a real nightmare. diff reveals often useless when the original
@@ -395,7 +395,7 @@
faster than translating everything again. I was able to gettextize the
existing French translation of the Perl documentation in one day, even if
things B<did> went wrong. That was more than two megabytes of text, and a
-new translation would have last months or more.
+new translation would have lasted months or more.
Let me explain the basis of the procedure first and I will come back on
hints to achieve it when the process goes wrong. To ease comprehension, the
@@ -435,7 +435,7 @@
Remove all extra parts of the translations, such as the section in which you
give the translator name and thank every people who contributed to the
-translation. Addendums, which are described in the next section, will allow
+translation. Addenda, which are described in the next section, will allow
you to re-add them afterward.
=item -
@@ -526,9 +526,9 @@
Because of the gettext approach, doing this becomes more difficult in po4a
than it was when simply editing a new file along the original one. But it
-remains possible, thanks to the so-called B<addendums>.
+remains possible, thanks to the so-called B<addenda>.
-It may help the comprehension to consider addendums as a sort of patches
+It may help the comprehension to consider addenda as a sort of patches
applied to the localized document after processing. They are rather
different from the usual patches (they have only one line of context, which
can embed perl regular expression, and they can only add new text without
@@ -852,7 +852,7 @@
=head2 Addendum: How does it work?
Well, that's pretty easy here. The translated document is not written
-directly to disk, but kept in memory until all addendum are applied. The
+directly to disk, but kept in memory until all the addenda are applied. The
algorithms involved here are rather straightforward. We look for a line
matching the position regexp, and insert the addendum before it if we're in
mode=before. If not, we search for the next line matching the boundary and
@@ -914,7 +914,7 @@
=item *
This approach is the one used by professional translators. I agree, that
-they have somehow different goals than open-source translators. The
+they have somewhat different goals than open-source translators. The
maintenance is for example often less critical to them since the content
changes rarely.
@@ -1136,7 +1136,7 @@
=item *
-Addendum are ... strange at the first glance.
+Addenda are... strange at the first glance.
=item *
Index: lib/Locale/Po4a/Chooser.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Chooser.pm,v
retrieving revision 1.21
diff -u -r1.21 Chooser.pm
--- lib/Locale/Po4a/Chooser.pm 12 Feb 2005 14:02:20 -0000 1.21
+++ lib/Locale/Po4a/Chooser.pm 14 Feb 2005 13:31:44 -0000
@@ -7,7 +7,7 @@
# under the terms of GPL (see COPYING).
#
# This module converts POD to PO file, so that it becomes possible to
-# translate POD formated documentation. See gettext documentation for
+# translate POD formatted documentation. See gettext documentation for
# more info about PO files.
############################################################################
@@ -53,13 +53,13 @@
sub list {
warn wrap_msg(gettext("List of valid formats:\n".
- " - kernelhelp: Help messages of each kernel compilation option.\n".
-# " - html: HTML documents (EXPERIMENTAL).\n".
- " - man: Good old manual page format.\n".
- " - pod: Perl Online Documentation format.\n".
- " - sgml: either debiandoc or docbook DTD.\n".
- " - dia: uncompressed Dia diagrams.\n".
- " - guide: Gentoo Linux's xml documentation format."));
+ " - kernelhelp: help messages of each kernel compilation option.\n".
+# " - html: HTML documents (EXPERIMENTAL).\n".
+ " - man: good old manual page format.\n".
+ " - pod: Perl Online Documentation format.\n".
+ " - sgml: either debiandoc or docbook DTD.\n".
+ " - dia: uncompressed Dia diagrams.\n".
+ " - guide: Gentoo Linux's xml documentation format.")."\n";
exit shift;
}
##############################################################################
Index: lib/Locale/Po4a/KernelHelp.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/KernelHelp.pm,v
retrieving revision 1.10
diff -u -r1.10 KernelHelp.pm
--- lib/Locale/Po4a/KernelHelp.pm 12 Feb 2005 14:02:20 -0000 1.10
+++ lib/Locale/Po4a/KernelHelp.pm 14 Feb 2005 13:31:44 -0000
@@ -7,7 +7,7 @@
# under the terms of GPL (see COPYING).
#
# This module converts POD to PO file, so that it becomes possible to
-# translate POD formated documentation. See gettext documentation for
+# translate POD formatted documentation. See gettext documentation for
# more info about PO files.
############################################################################
Index: lib/Locale/Po4a/Man.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Man.pm,v
retrieving revision 1.75
diff -u -r1.75 Man.pm
--- lib/Locale/Po4a/Man.pm 13 Feb 2005 23:06:45 -0000 1.75
+++ lib/Locale/Po4a/Man.pm 14 Feb 2005 13:31:44 -0000
@@ -398,7 +398,7 @@
sub pre_trans {
my ($self,$str,$ref,$type)=@_;
- # Preformating, so that translators don't see
+ # Preformatting, so that translators don't see
# strange chars
my $origstr=$str;
print STDERR "pre_trans($str)="
@@ -455,7 +455,7 @@
print STDERR "post_trans($str)="
if ($debug{'postrans'});
- # Post formating, so that groff see the strange chars
+ # Post formatting, so that groff see the strange chars
$str =~ s|\\-|-|sg; # in case the translator added some of them manually
# change hyphens to minus signs
# (this shouldn't be done for \s-<number> font size modifiers)
@@ -685,7 +685,7 @@
# .Dd => Indicates that this is a mdoc page
if ($macro eq 'Dd') {
die wrap_mod("po4a::man", dgettext("po4a",
- "This page seems to be a mdoc(7) formated one. This is not supported (yet)."));
+ "This page seems to be a mdoc(7) formatted one. This is not supported (yet)."));
}
unshift @args,$self;
Index: lib/Locale/Po4a/Po.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Po.pm,v
retrieving revision 1.34
diff -u -r1.34 Po.pm
--- lib/Locale/Po4a/Po.pm 12 Feb 2005 14:02:21 -0000 1.34
+++ lib/Locale/Po4a/Po.pm 14 Feb 2005 13:31:44 -0000
@@ -292,15 +292,15 @@
if ($poorig->count_entries() > $potrans->count_entries()) {
warn wrap_mod("po4a gettextize", dgettext("po4a",
- "Original have more strings that the translation (%d>%d). ".
+ "Original has more strings that the translation (%d>%d). ".
"Please fix it by editing the translated version to add some dummy entry."),
$poorig->count_entries() , $potrans->count_entries());
} elsif ($poorig->count_entries() < $potrans->count_entries()) {
warn wrap_mod("po4a gettextize", dgettext("po4a",
- "Original have less strings that the translation (%d<%d). ".
+ "Original has less strings than the translation (%d<%d). ".
"Please fix it by removing the extra entry from the translated file. ".
"You may need an addendum (cf po4a(7)) to reput the chunk in place after gettextization. ".
- "A possible cause is that a text dupplicated in the original is not translated the same way each time. Remove one of the translations, and you're fine."),
+ "A possible cause is that a text duplicated in the original is not translated the same way each time. Remove one of the translations, and you're fine."),
$poorig->count_entries(), $potrans->count_entries());
}
@@ -773,7 +773,7 @@
=item wrap
boolean indicating whether whitespaces can be mangled in cosmetic
-reformatings. If true, the string is canonized before use.
+reformattings. If true, the string is canonized before use.
This information is written to the po file using the 'wrap' or 'no-wrap' flag.
Index: lib/Locale/Po4a/Pod.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Pod.pm,v
retrieving revision 1.14
diff -u -r1.14 Pod.pm
--- lib/Locale/Po4a/Pod.pm 7 Jan 2005 22:50:52 -0000 1.14
+++ lib/Locale/Po4a/Pod.pm 14 Feb 2005 13:31:45 -0000
@@ -7,7 +7,7 @@
# under the terms of GPL (see COPYING file).
#
# This module converts POD to PO file, so that it becomes possible to
-# translate POD formated documentation. See gettext documentation for
+# translate POD formatted documentation. See gettext documentation for
# more info about PO files.
############################################################################
Index: lib/Locale/Po4a/Sgml.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Sgml.pm,v
retrieving revision 1.44
diff -u -r1.44 Sgml.pm
--- lib/Locale/Po4a/Sgml.pm 12 Feb 2005 14:02:21 -0000 1.44
+++ lib/Locale/Po4a/Sgml.pm 14 Feb 2005 13:31:45 -0000
@@ -91,7 +91,7 @@
By default, msgids containing only one entity (like '&version;') are skipped
for the translator comfort. Activating this option prevents this
optimisation. It can be useful if the document contains a construction like
-"<title>&Acute;</title>", even if I doubt such things to ever happen...
+"<title>Á</title>", even if I doubt such things to ever happen...
=back
@@ -117,12 +117,12 @@
the document (not in a E<lt>pE<gt> tag or so).
Everything works well with nsgmls's output redirected that way, but it will
-prevent us to detect that the document is badly formated.
+prevent us to detect that the document is badly formatted.
=item *
It does work only with the debiandoc and docbook dtd. Adding support for a
-new dtd should be very easy. The mechanism is the same for all dtd, you just
+new dtd should be very easy. The mechanism is the same for every dtd, you just
have to give a list of the existing tags and some of their characteristics.
I agree, this needs some more documentation, but it is still considered as
@@ -131,7 +131,7 @@
=item *
Warning, support for dtds is quite experimental. I did not read any
-reference manual to find the definition of all tags. I did add tag
+reference manual to find the definition of every tag. I did add tag
definition to the module 'till it works for some documents I found on the
net. If your document use more tags than mine, it won't work. But as I said
above, fixing that should be quite easy.
@@ -140,7 +140,7 @@
this document is quite big, and should use most of the docbook
specificities.
-For debiandoc, I tested some of the manual of the DDP, but not all yet.
+For debiandoc, I tested some of the manuals from the DDP, but not all yet.
=item *
Index: lib/Locale/Po4a/TeX.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/TeX.pm,v
retrieving revision 1.15
diff -u -r1.15 TeX.pm
--- lib/Locale/Po4a/TeX.pm 13 Feb 2005 23:06:45 -0000 1.15
+++ lib/Locale/Po4a/TeX.pm 14 Feb 2005 13:31:45 -0000
@@ -164,7 +164,7 @@
sub pre_trans {
my ($self,$str,$ref,$type)=@_;
- # Preformating, so that translators don't see
+ # Preformatting, so that translators don't see
# strange chars
my $origstr=$str;
print STDERR "pre_trans($str)="
Index: lib/Locale/Po4a/TransTractor.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/TransTractor.pm,v
retrieving revision 1.57
diff -u -r1.57 TransTractor.pm
--- lib/Locale/Po4a/TransTractor.pm 12 Feb 2005 14:02:21 -0000 1.57
+++ lib/Locale/Po4a/TransTractor.pm 14 Feb 2005 13:31:45 -0000
@@ -187,7 +187,7 @@
=item d.
-Reads and applies all the addendum specified
+Reads and applies all the addenda specified
=item e.
@@ -233,11 +233,11 @@
=item addendum (@)
-list of filenames where we should read the addendum from.
+list of filenames where we should read the addenda from.
=item addendum_charset ($)
-Charset for the addendum.
+Charset for the addenda.
=back
@@ -489,13 +489,13 @@
=cut
-=head2 Manipulating addendum
+=head2 Manipulating addenda
=over 4
=item addendum($)
-Please refer to L<po4a(7)|po4a.7> for more information on what addendums are,
+Please refer to L<po4a(7)|po4a.7> for more information on what addenda are,
and how translators should write them. To apply an addendum to the translated
document, simply pass its filename to this function and you are done ;)
--Boundary-00=_SSLECyVSdTTXR2S--