X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/e397888a77b10d96437754779062852f56d96765..741b26aa176b34d0359a2b89dd6d8293fcdf2b3d:/doc/plugins/po.mdwn diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn index 09df26394..919864ede 100644 --- a/doc/plugins/po.mdwn +++ b/doc/plugins/po.mdwn @@ -129,6 +129,10 @@ Usage Templates --------- +When `po_link_to` is not set to `negotiated`, one should replace some +occurrences of `BASEURL` with `HOMEPAGEURL` to get correct links to +the wiki homepage. + The `ISTRANSLATION` and `ISTRANSLATABLE` variables can be used to display things only on translatable or translation pages. @@ -194,14 +198,18 @@ Also, when the plugin has just been enabled, or when a page has just been declared as being translatable, the needed POT and PO files are created, and the PO files are checked into version control. -Discussion pages ----------------- +Discussion pages and other sub-pages +------------------------------------ Discussion should happen in the language in which the pages are written for real, *i.e.* the "master" one. If discussion pages are enabled, "slave" pages therefore link to the "master" page's discussion page. +Likewise, "slave" pages are not supposed to have sub-pages; +[[WikiLinks|wikilink]] that appear on a "slave" page therefore link to +the master page's sub-pages. + Translating ----------- @@ -211,6 +219,22 @@ interface could also be implemented at some point). If [[tips/untrusted_git_push]] is setup, one can edit the PO files in one's preferred `$EDITOR`, without needing to be online. +Markup languages support +------------------------ + +Markdown is well supported. Some other markup languages supported by +ikiwiki mostly work, but some pieces of syntax are not rendered +correctly on the slave pages: + +* [[reStructuredText|rst]]: anonymous hyperlinks and internal + cross-references +* [[wikitext]]: conversion of newlines to paragraphs +* [[creole]]: verbatim text is wrapped, tables are broken +* [[html]] and LaTeX: not supported yet; the dedicated po4a modules + could be used to support them, but they would need a security audit +* other markup languages have not been tested. + + TODO ==== @@ -295,6 +319,8 @@ means the `Text` module only. variables; they seem safe to me, but someone more expert than me will need to check. Joey? + > Freaky code, but seems ok due to use of `quotementa`. + ##### Text::WrapI18N `Text::WrapI18N` can cause DoS (see the @@ -314,6 +340,34 @@ in this field. Joey? [[--intrigeri]] > familiar with. I can learn and do it, in case no Perl wizard > volunteers to provide the po4a patch. [[--intrigeri]] +>> That doesn't really need to be in a BEGIN. This patch moves it to +>> `import`, and makes this disable wrap18n: +>> `use Locale::Po4a::Common q{nowrapi18n}` --[[Joey]] + +
+--- /usr/share/perl5/Locale/Po4a/Common.pm	2008-07-21 14:54:52.000000000 -0400
++++ Common.pm	2008-11-11 18:27:34.000000000 -0500
+@@ -30,8 +30,16 @@
+ use strict;
+ use warnings;
+ 
+-BEGIN {
+-    if (eval { require Text::WrapI18N }) {
++sub import {
++    my $class=shift;
++    my $wrapi18n=1;
++    if ($_[0] eq 'nowrapi18n') {
++    	shift;
++	$wrapi18n=0;
++    }
++    $class->export_to_level(1, $class, @_);
++
++    if ($wrapi18n && eval { require Text::WrapI18N }) {
+     
+         # Don't bother determining the wrap column if we cannot wrap.
+         my $col=$ENV{COLUMNS};
+
+ ##### Term::ReadKey `Term::ReadKey` is not a hard dependency in our case, *i.e.* po4a @@ -358,6 +412,92 @@ a program in order to easily detect some of the most obvious DoS. > po4a was not fuzzy-tested, but according to one of its developers, > "it would be really appreciated". [[--intrigeri]] +Test conditions: + +- a 21M file containing 100 concatenated copies of all the files in my + `/usr/share/common-licenses/`; I had no existing PO file or + translated versions at hand, which renders these tests + quite incomplete. +- po4a was the Debian 0.34-2 package; the same tests were also run + after replacing the `Text` module with the CVS one (the core was not + changed in CVS since 0.34-2 was released), without any significant + difference in the results. +- Perl 5.10.0-16 + +#### po4a-gettextize + +`po4a-gettextize` uses more or less the same po4a features as our +`refreshpot` function. + +Without specifying an input charset, zzuf'ed `po4a-gettextize` quickly +errors out, complaining it was not able to detect the input charset; +it leaves no incomplete file on disk. + +So I had to pretend the input was in UTF-8, as does the po plugin. + +Two ways of crashing were revealed by this command-line: + + zzuf -vc -s 0:100 -r 0.1:0.5 \ + po4a-gettextize -f text -o markdown -M utf-8 -L utf-8 \ + -m LICENSES >/dev/null + +They are: + + Malformed UTF-8 character (UTF-16 surrogate 0xdcc9) in substitution iterator at /usr/share/perl5/Locale/Po4a/Po.pm line 1443. + Malformed UTF-8 character (fatal) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443. + +and + + Malformed UTF-8 character (UTF-16 surrogate 0xdcec) in substitution (s///) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443. + Malformed UTF-8 character (fatal) at /usr/share/perl5/Locale/Po4a/Po.pm line 1443. + +Perl seems to exit cleanly, and an incomplete PO file is written on +disk. I not sure whether if this is a bug in Perl or in `Po.pm`. + +> It's fairly standard perl behavior when fed malformed utf-8. As long as it doesn't +> crash ikiwiki, it's probably acceptable. Ikiwiki can do some similar things itself when fed malformed utf-8 (doesn't crash tho) --[[Joey]] + +#### po4a-translate + +`po4a-translate` uses more or less the same po4a features as our +`filter` function. + +Without specifying an input charset, same behaviour as +`po4a-gettextize`, so let's specify UTF-8 as input charset as of now. + + zzuf -cv \ + po4a-translate -d -f text -o markdown -M utf-8 -L utf-8 \ + -k 0 -m LICENSES -p LICENSES.fr.po -l test.fr + +... prints tons of occurences of the following error, but a complete +translated document is written (obviously with some weird chars +inside): + + Use of uninitialized value in string ne at /usr/share/perl5/Locale/Po4a/TransTractor.pm line 854. + Use of uninitialized value in string ne at /usr/share/perl5/Locale/Po4a/TransTractor.pm line 840. + Use of uninitialized value in pattern match (m//) at /usr/share/perl5/Locale/Po4a/Po.pm line 1002. + +While: + + zzuf -cv -s 0:10 -r 0.001:0.3 \ + po4a-translate -d -f text -o markdown -M utf-8 -L utf-8 \ + -k 0 -m LICENSES -p LICENSES.fr.po -l test.fr + +... seems to lose the fight, at the `readpo(LICENSES.fr.po)` step, +against some kind of infinite loop, deadlock, or any similar beast. +It does not seem to eat memory, though. + +Whatever format module is used does not change anything. This is thus +probably a bug in po4a's core or in a lib it depends on. + +The sub `read`, in `TransTractor.pm`, seems to be a good debugging +starting point. + +#### msgmerge + +`msgmerge` is run in our `refreshpofiles` function. I did not manage +to crash it with `zzuf`. + gettext/po4a rough corners -------------------------- @@ -376,22 +516,16 @@ gettext/po4a rough corners into the Pot file, and let it propagate; should be fixed in `773de05a7a1ee68d2bed173367cf5e716884945a`, time will tell. -Misc. improvements ------------------- - -### page titles +Better links +------------ -Use nice page titles from meta plugin in links, as inline already -does. This is actually a duplicate for -[[bugs/pagetitle_function_does_not_respect_meta_titles]], which might -be fixed by something like [[todo/using_meta_titles_for_parentlinks]]. +### Page title in links -### source files format - -Markdown is supported, great, but what about others? The set of file -formats supported both in ikiwiki and po4a probably is greater than -`{markdown}`. Warning: the po4a modules are the place where one can -expect security issues. +Using the fix to +[[bugs/pagetitle_function_does_not_respect_meta_titles]] from +[[intrigeri]]'s `meta` branch, the generated links' text is based on +the page titles set with the [[meta|plugins/meta]] plugin. This has to +be merged upstream, though. Translation quality assurance ----------------------------- @@ -404,3 +538,69 @@ A new `cansave` type of hook would be needed to implement this. Note: committing to the underlying repository is a way to bypass this check. + +Creating new pages on the web +----------------------------- + +See [[contrib/po|contrib/po]]. + +Renaming/deleting pages +----------------------- + +Renaming or deleting a translation in the CGI should be forbidden. +Implementing this requires two new hooks: `canrename` and `canremove`, +that would be run respectively by the `rename` and the `remove` plugins. + +Robustness tests +---------------- + +### Disabling the plugin + +- enabling the plugin with `po_translatable_pages` set +- enabling the plugin without `po_translatable_pages` set: **OK** +- disabling the plugin: **OK** + +### Changing the plugin config + +- adding existing pages to `po_translatable_pages`: **OK** +- removing existing pages from `po_translatable_pages`: **OK** +- adding a language to `po_slave_languages`: **OK** +- removing a language from `po_slave_languages`: **OK** +- changing `po_master_language`: **OK** +- replacing `po_master_language` with a language previously part of + `po_slave_languages`: needs two rebuilds, but **OK** (this is quite + a perverse test actually) + +### Creating pages + +- creating a master page via RCS: **OK** +- creating a master page via CGI: **OK** + +### Deleting pages + +- removing a master page via RCS: **OK** +- removing a translation via RCS: **OK** +- removing a master page via CGI: **OK** +- removing a translation via CGI: **OK** + +### Renaming pages + +- renaming a master page via RCS: **OK** (but the old translations + are lost, because not all RCS track file renaming) +- renaming a master page and its translations via RCS: **OK** +- renaming a master page via CGI: **OK** +- renaming a translation via RCS +- renaming a translation via CGI + +### Misc + +- general test with `usedirs` disabled: **OK** +- general test with `indexpages` enabled +- general test with `po_link_to=default` + +Documentation +------------- + +Maybe write separate documentation depending on the people it targets: +translators, wiki administrators, hackers. This plugin may be complex +enough to deserve this.