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

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 2f413e275..d16d13edc 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
 -----------
 
@@ -295,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
@@ -314,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
@@ -400,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
@@ -459,22 +500,44 @@ gettext/po4a rough corners
   into the Pot file, and let it propagate; should be fixed in
   `773de05a7a1ee68d2bed173367cf5e716884945a`, time will tell.
 
-Misc. improvements
-------------------
+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]].
 
-### page titles
+### Backlinks
 
-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]].
+They are not updated when the source page changes (e.g. meta title).
 
-### source files format
+Page formats
+------------
 
-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.
+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.
+
+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.
+
+**TODO**: test the more popular formats and write proper documentation
+about it.
 
 Translation quality assurance
 -----------------------------
@@ -487,3 +550,25 @@ 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]].
+
+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
+-------------
+
+Maybe write separate documentation depending on the people it targets:
+translators, wiki administrators, hackers. This plugin may be complex
+enough to deserve this.