po/todo: added robustness tests that have to be done

[ikiwiki.git] / doc / plugins / po.mdwn

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index ca5f4af6bbd102a64a55def28da85ead925f7c71..d16d13edc7e97e5708da80b14e276a66fdbe2735 100644 (file)
--- a/doc/plugins/po.mdwn
+++ b/doc/plugins/po.mdwn
@@ -198,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
 -----------
 
@@ -299,6 +303,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
@@ -318,6 +324,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]]
+
+<pre>
+--- /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};
+</pre>
+
 ##### Term::ReadKey
 
 `Term::ReadKey` is not a hard dependency in our case, *i.e.* po4a
@@ -404,6 +438,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
@@ -468,7 +505,7 @@ Better links
 
 ### Page title in links
 
-To use the page titles set with the [meta](plugins/meta) plugin when
+To use the page titles set with the [[meta|plugins/meta]] plugin when
 rendering links would be very much nicer, than the current
 "filename.LL" format. This is actually a duplicate for
 [[bugs/pagetitle_function_does_not_respect_meta_titles]].
@@ -488,7 +525,7 @@ Page formats
 
 Markdown is well supported, great, but what about others?
 
-The [po](plugins/po) uses `Locale::Po4a::Text` for every page format;
+The [[po|plugins/po]] uses `Locale::Po4a::Text` for every page format;
 this can be expected to work out of the box with most other wiki-like
 formats supported by ikiwiki. Some of their ad-hoc syntax might be
 parsed in a strange way, but the worst problems I can imagine would be
@@ -519,6 +556,16 @@ Creating new pages on the web
 
 See [[contrib/po]].
 
+Robustness tests
+----------------
+
+- adding and removing pages from `po_translatable_pages`
+- creating and removing pages listed in `po_translatable_pages`
+- enabling the plugin, with and without `po_translatable_pages` set
+- disabling the plugin
+- test with `usedirs` disabled
+- test with `indexpages` enabled
+
 Documentation
 -------------