X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/3d8d47d7858ae0e043a28f348fe8aec444d0d35a..a8105f68590c7aa56fc37ec62df854546a119060:/doc/plugins/po.mdwn?ds=inline diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn index 2f413e275..5337a2ce2 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 @@ -400,6 +454,9 @@ and 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 @@ -459,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 ----------------------------- @@ -487,3 +538,62 @@ 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]]. + +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.