X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/b7a4e5a51cbb3867e37f4ed5de8f94e0d41fd152..c8e3136d0091bd024e6dc1f3c21a10a92f2017d4:/doc/plugins/po.mdwn

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 04a45f8f2..9298b3d37 100644
--- 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
 -----------
 
@@ -215,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
 ====
 
@@ -299,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
@@ -318,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]]
+
+<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
@@ -349,6 +399,10 @@ use in our case, I suggest we define `ENV{COLUMNS}` before loading
 `refreshpofiles()` runs this external program. A po4a developer
 answered he does "not expect any security issues from it".
 
+### msgfmt
+
+`isvalidpo()` runs this external program. Its security should be checked.
+
 ### Fuzzing input
 
 I was not able to find any public information about gettext or po4a
@@ -404,6 +458,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,56 +525,42 @@ Better links
 
 ### Page title in links
 
-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]].
-
-Going to work on this in my `meta` branch.
-
-### Translation status in links
-
-See [[contrib/po]].
-
-### Backlinks
+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.
 
-They are not updated when the source page changes (e.g. meta title).
-
-Page formats
-------------
-
-Markdown is well supported, great, but what about others?
-
-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
-wrapping issues; e.g. there is code in po4a dedicated to prevent
-re-wrapping the underlined Markdown headers.
+Robustness tests
+----------------
 
-While it would be easy to better support formats such as [[html]] or
-LaTeX, by using for each one the dedicated po4a module, this can be
-problematic from a security point of view.
+### Enabling/disabling the plugin
 
-**TODO**: test the more popular formats and write proper documentation
-about it.
+- enabling the plugin with `po_translatable_pages` set
+- enabling the plugin without `po_translatable_pages` set: **OK**
+- disabling the plugin: **OK**
 
-Translation quality assurance
------------------------------
+### Changing the plugin config
 
-Modifying a PO file via the CGI must be forbidden if the new version
-is not a valid PO file. As a bonus, check that it provides a more
-complete translation than the existing one.
+- 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)
 
-A new `cansave` type of hook would be needed to implement this.
+### Creating/deleting/renaming pages
 
-Note: committing to the underlying repository is a way to bypass
-this check.
+All cases of master/slave page creation/deletion/rename, both via RCS
+and via CGI, have been tested.
 
-Creating new pages on the web
------------------------------
+### Misc
 
-See [[contrib/po]].
+- general test with `usedirs` disabled: **OK**
+- general test with `indexpages` enabled
+- general test with `po_link_to=default`
 
 Documentation
 -------------