[Po4a-devel][CVS] po4a/lib/Locale/Po4a Pod.pm,1.10,1.11 Man.pm,1.23,1.24 Sgml.pm,1.32,1.33 Xml.pm,1.15,1.16 Dia.pm,1.4,1.5
Jordi Vilalta
po4a-devel@lists.alioth.debian.org
Mon, 09 Aug 2004 12:58:32 +0000
Update of /cvsroot/po4a/po4a/lib/Locale/Po4a
In directory haydn:/tmp/cvs-serv22311
Modified Files:
Pod.pm Man.pm Sgml.pm Xml.pm Dia.pm
Log Message:
Little documentation enhancements (fuzzy time!). Correct me if I broke the
meaning of some paragraphs. I tried to rewrite some small parts to reflect
better the code.
Index: Dia.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Dia.pm,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- Dia.pm 7 Aug 2004 04:51:33 -0000 1.4
+++ Dia.pm 9 Aug 2004 12:58:30 -0000 1.5
@@ -76,7 +76,7 @@
=head1 SEE ALSO
-L<po4a(7)>, L<Locale::Po4a::TransTractor(3pm)>, L<Locale::Po4a::Pod(3pm)>.
+L<po4a(7)|po4a.7>, L<Locale::Po4a::TransTractor(3pm)>, L<Locale::Po4a::Pod(3pm)>.
=head1 AUTHORS
Index: Pod.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Pod.pm,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- Pod.pm 30 Jul 2004 00:17:41 -0000 1.10
+++ Pod.pm 9 Aug 2004 12:58:29 -0000 1.11
@@ -163,7 +163,7 @@
CE<lt>" #n"E<gt>
-Lake of luck, in the po4a version, this was splited on the space by the
+Lack of luck, in the po4a version, this was splited on the space by the
wrapping. As result, in the original version, the man contain
" #n"
@@ -195,7 +195,7 @@
calls either parse_from_filehandle() or parse_from_file().
new() can take options, in the form of key/value pairs, that control the
-behavior of the parser. The recognized options common to all Pod:;Parser
+behavior of the parser. The recognized options common to all Pod::Parser
children are:
=over 4
@@ -256,9 +256,9 @@
=item pomode
-In fact, this parser can work in to modes. When pomode=write, it reads a
-pod file, and extract the string which should be translated to a pot
-file. When pomode=read (the default), it reads a pod file and write a
+In fact, this parser can work in two modes. When pomode=write, it reads a
+pod file, and extracts the strings which should be translated to a pot
+file. When pomode=read (the default), it reads a pod file and writes a
similar pod file, but translating all strings on the way (the translation
is read from the po file).
@@ -271,7 +271,7 @@
=head1 SEE ALSO
-L<Pod::Parser>, L<po4a(7)>, L<Locale::Po4a::TransTractor(3pm)>,
+L<Pod::Parser>, L<po4a(7)|po4a.7>, L<Locale::Po4a::TransTractor(3pm)>,
L<Locale::Po4a::Man(3pm)>,
=head1 AUTHORS
Index: Xml.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Xml.pm,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- Xml.pm 8 Aug 2004 19:10:25 -0000 1.15
+++ Xml.pm 9 Aug 2004 12:58:30 -0000 1.16
@@ -153,11 +153,11 @@
Example: WE<lt>chapterE<gt><title>
-=item attributes (TODO)
+=item attributes
Space-separated list of the tag's attributes you want to translate. You can
specify the attributes by their name (for example, "lang"), but you can
-prefix it with a tag hierarchy, to specify that this tag will only be
+prefix it with a tag hierarchy, to specify that this attribute will only be
translated when it's into the specified tag. For example: <bbb><aaa>lang
specifies that the lang attribute will only be translated if it's into an
<aaa> tag, and it's into a <bbb> tag.
@@ -194,9 +194,9 @@
}
}
- #It will mantain the list of the translateable tags
+ #It will mantain the list of the translatable tags
$self->{tags}=();
- #It will mantain the list of the translateable attributes
+ #It will mantain the list of the translatable attributes
$self->{attributes}=();
#It will mantain the list of the inline tags
$self->{inline}=();
@@ -233,6 +233,24 @@
that contains extra information to control what strings to translate, how
to translate them and to generate the comment.
+This options hash has different contents depending on what kind of string
+it is (specified in an entry of this hash):
+
+=over
+
+=item type="tag"
+
+The found string is the contents of a translatable tag. The entry "tag_options"
+contains the option characters in front of the tag hierarchy in the module
+"tags" option.
+
+=item type="attribute"
+
+Means that the found string is the value of a translatable attribute. The
+entry "attribute" has the name of the attribute.
+
+=back
+
It must return the text that will replace the original in the translated
document. Here's a basic example of this function:
@@ -306,16 +324,17 @@
=item f_extract
-If you leave this key undefined, the extraction function will have to extract
-the tag itself. It's useful for tags that can have other tags or special
-structures in them, so that the main parser doesn't get mad. This function
-receives a boolean that says if the tag should be removed from the input
-stream or not.
+If you leave this key undefined, the generic extraction function will have to
+extract the tag itself. It's useful for tags that can have other tags or
+special structures in them, so that the main parser doesn't get mad. This
+function receives a boolean that says if the tag should be removed from the
+input stream or not.
=item f_translate
-This function returns the translated tag (translated attributes or all needed
-transformations) as a single string.
+This function receives the tag (in the get_string_until() format) and returns
+the translated tag (translated attributes or all needed transformations) as a
+single string.
=back
@@ -374,10 +393,10 @@
my $tag = $self->join_lines(@tag);
$tag =~ /encoding=(("|')|)(.*?)(\s|\2)/s;
my $in_charset=$3;
- my $out_charset=$self->detected_charset($in_charset);
+ $self->detected_charset($in_charset);
+ my $out_charset=$self->get_out_charset;
- $tag =~ s/$in_charset/$out_charset/
- unless !defined($out_charset) or $out_charset eq "";
+ $tag =~ s/$in_charset/$out_charset/;
return $tag;
}
@@ -504,7 +523,7 @@
=over 4
-=item get_path
+=item get_path()
This function returns the path to the current tag from the document's root,
in the form <html><body><p>.
@@ -520,7 +539,7 @@
}
}
-=item tag_type
+=item tag_type()
This function returns the index from the tag_types list that fits to the next
tag in the input stream, or -1 if it's at the end of the input file.
@@ -568,7 +587,7 @@
}
}
-=item extract_tag
+=item extract_tag($$)
This function returns the next tag from the input stream without the beginning
and end, in an array form, to mantain the references from the input file. It
@@ -593,7 +612,7 @@
return ($eof,@tag);
}
-=item get_tag_name
+=item get_tag_name(@)
This function returns the name of the tag passed as an argument, in the array
form returned by extract_tag.
@@ -606,7 +625,7 @@
return $1;
}
-=item breaking_tag
+=item breaking_tag()
This function returns a boolean that says if the next tag in the input stream
is a breaking tag or not (inline tag). It leaves the input stream intact.
@@ -631,7 +650,7 @@
return $break;
}
-=item treat_tag
+=item treat_tag()
This function translates the next tag from the input stream. Using each
tag type's custom translation functions.
@@ -659,12 +678,12 @@
return $eof;
}
-=item tag_in_list
+=item tag_in_list($@)
This function returns a string value that says if the first argument (a tag
hierarchy) matches any of the tags from the second argument (a list of tags
or tag hierarchies). If it doesn't match, it returns 0. Else, it returns the
-matched tag options (the characters in front of the tag) or 1 (if that tag
+matched tag's options (the characters in front of the tag) or 1 (if that tag
doesn't have options).
=back
@@ -704,12 +723,12 @@
=over 4
-=item treat_attributes
+=item treat_attributes(@)
This function handles the tags attributes' translation. It receives the tag
without the beginning / end marks, and then it finds the attributes, and it
-translates the translateables (specified by the option "attributes"). This
-returns a plain string with the translated tag.
+translates the translatables (specified by the module option "attributes").
+This returns a plain string with the translated tag.
=back
@@ -894,7 +913,7 @@
=over 4
-=item treat_options
+=item treat_options()
This function fills the internal structures that contain the tags, attributes
and inline data with the options of the module (specified in the command-line
@@ -924,10 +943,10 @@
=over
-=item get_string_until
+=item get_string_until($%)
This function returns an array with the lines (and references) from the input
-stream until it finds the first argument. The second argument is an options
+document until it finds the first argument. The second argument is an options
hash. Value 0 means disabled (the default) and 1, enabled.
The valid options are:
@@ -1014,7 +1033,7 @@
return ($eof,@text);
}
-=item skip_spaces
+=item skip_spaces(\@)
This function receives as argument the reference to a paragraph (in the format
returned by get_string_until), skips his heading spaces and returns them as
@@ -1040,7 +1059,7 @@
return $space;
}
-=item join_lines
+=item join_lines(@)
This function returns a simple string with the text from the argument array
(discarding the references).
@@ -1062,12 +1081,13 @@
=head1 STATUS OF THIS MODULE
-Well... hmm... If this works for you now, you're using a very simple
-document format ;)
+This module can translate tags and attributes.
-=head1 TODO LIST
+Support for entities and included files is in the TODO list.
-XML HEADER (ENCODING)
+The writing of derivate modules is rather limited.
+
+=head1 TODO LIST
DOCTYPE (ENTITIES)
@@ -1080,7 +1100,7 @@
=head1 SEE ALSO
-L<po4a(7)>, L<Locale::Po4a::TransTractor(3pm)>.
+L<po4a(7)|po4a.7>, L<Locale::Po4a::TransTractor(3pm)>.
=head1 AUTHORS
Index: Sgml.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Sgml.pm,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -d -r1.32 -r1.33
--- Sgml.pm 7 Aug 2004 21:09:02 -0000 1.32
+++ Sgml.pm 9 Aug 2004 12:58:30 -0000 1.33
@@ -78,9 +78,9 @@
=item ignore
Tags ignored and considered as plain char data by po4a. That is to say that
-they can be part of a msgid. For example, E<gt>bE<lt> is a good candidate
+they can be part of a msgid. For example, E<lt>bE<gt> is a good candidate
for this category since putting it in the translate section would create
-msgid not being whole sentences, which is bad.
+msgids not being whole sentences, which is bad.
=item force
@@ -88,7 +88,7 @@
=item include-all
-By default, msgid containing only one entity (like '&version') are skipped
+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...
@@ -850,6 +850,7 @@
}
1;
+
=head1 AUTHORS
This module is an adapted version of sgmlspl (SGML postprocesser for the
Index: Man.pm
===================================================================
RCS file: /cvsroot/po4a/po4a/lib/Locale/Po4a/Man.pm,v
retrieving revision 1.23
retrieving revision 1.24
diff -u -d -r1.23 -r1.24
--- Man.pm 8 Aug 2004 20:36:19 -0000 1.23
+++ Man.pm 9 Aug 2004 12:58:30 -0000 1.24
@@ -18,8 +18,8 @@
This module tries pretty hard to make translator's life easier. For that,
the text presented to translators isn't a verbatim copy of the text found
-in the man page. Indeed, the cruder parts of the nroff format are hiden, so
-that translators can't mess up with it.
+in the man page. Indeed, the cruder parts of the nroff format are hidden, so
+that translators can't mess up with them.
=head2 Text wrapping
@@ -74,9 +74,9 @@
real nroff interpreter. It would be possible to do a real nroff
interpreter, to allow authors to use all the existing macros, or even to
define new ones in their pages, but we didn't want to. It would be too
-difficult, and we didn't though it was necessary. We do think that if
+difficult, and we thought it wasn't necessary. We do think that if
manpage authors want to see their production translated, they may have to
-adapt to ease the work of translaters.
+adapt to ease the work of translators.
So, the man parser implemented in po4a have some known limitations we are
not really inclined to correct, and which will constitute some pitfalls
@@ -85,32 +85,32 @@
=head2 Don't use the mdoc macro set
-The macro set described in mdoc(7) (and widly used under BSD, IIRC) isn't
+The macro set described in mdoc(7) (and widely used under BSD, IIRC) isn't
supported at all by po4a, and won't be. It would need a completely separate
-parser for this, and I'm not inclined to do so. On my machine, there is
-only 63 pages based on mdoc, from 4323 pages. If someone implement the mdoc
+parser for this, and I'm not inclined to do so. On my machine, there are
+only 63 pages based on mdoc, from 4323 pages. If someone implements the mdoc
support, I'll happilly include this, though.
=head2 Don't programm in nroff
nroff is a complete programming language, with macro definition,
conditionals and so on. Since this parser isn't a fully featured nroff
-interpreter, it will fail on pages using these facilities (There is about
+interpreter, it will fail on pages using these facilities (There are about
200 such pages on my box).
=head2 Avoid file inclusion when possible
The '.so' groff macro used to include another file in the current one is
-supported, but from my personnal experiment, it makes harder to manipulate
+supported, but from my own experience, it makes harder to manipulate
the man page, since all files have to be installed in the right location so
that you can see the result (ie, it breaks somehow the '-l' option of man).
=head2 Use the plain macro set
-There is still some macros which are not supported by po4a::man. This is
+There are still some macros which are not supported by po4a::man. This is
only because I failed to find any documentation about them. Here is the
list of unsupported macros used on my box. Note that this list isn't
-exaustive since the program fails on the first encountered unsupported
+exhaustive since the program fails on the first encountered unsupported
macro. If you have any information about some of these macros, I'll
happilly add support for them. Because of these macros, about 250 pages on
my box are inaccessible to po4a::man.
@@ -131,13 +131,13 @@
Some authors escape spaces to make sure that the wrapping tool won't mangle
them. po4a::man I<will> eat them. Use the .nf/.fi groff macro to control
-wheather the text should be wrapped or not.
+whether the text should be wrapped or not.
=head2 Don't mess nest font specifier.
In order to make translator's life easier, po4a::man will change all font
specifiers in the way explained above. This process is sometimes fragile,
-and need some love from you. For example, don't write the following:
+and needs some love from you. For example, don't write the following:
\fB bold text \fI italic text \fR back to roman
@@ -156,7 +156,7 @@
=head2 Conclusion
-To summarise this section, keep simple, and don't try to be cleaver while
+To summarise this section, keep simple, and don't try to be clever while
authoring your man pages. A lot of things are possible in nroff, and not
supported by this parser. For example, don't try to mess with \c to
interrupt the text processing (like 40 pages on my box do). Or, be sure to
@@ -167,8 +167,8 @@
Of course, another possibility is to use another format, more translator
friendly (like pod using po4a::pod, or one of the xml familly like sgml),
but thanks to po4a::man it isn't needed anymore. That being said, if the
-source format of your documentation is pod, or xml, it may be cleaver to
-translate the source format and not this generated one. In most case,
+source format of your documentation is pod, or xml, it may be clever to
+translate the source format and not this generated one. In most cases,
po4a::man will detect generated pages and issue a warning. It will even
refuse to process Pod generated pages, because those pages are perfectly
handled by po4a::pod, and because their nroff counterpart defines a lot of
@@ -219,7 +219,7 @@
=head1 SEE ALSO
-L<po4a(7)>, L<Locale::Po4a::TransTractor(3pm)>,
+L<po4a(7)|po4a.7>, L<Locale::Po4a::TransTractor(3pm)>,
L<Locale::Po4a::Pod(3pm)>.
=head1 AUTHORS