po/todo: added bug report for weird Perl warnings

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

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 2f413e275c8aac3f1f1297819331004608598e5b..2f359bb8389e00ca318978c69e445e37e288e4a4 100644 (file)
--- a/doc/plugins/po.mdwn
+++ b/doc/plugins/po.mdwn
@@ -459,22 +459,44 @@ gettext/po4a rough corners
   into the Pot file, and let it propagate; should be fixed in
   `773de05a7a1ee68d2bed173367cf5e716884945a`, time will tell.
 
-Misc. improvements
-------------------
+When committing a translatable page to the repository, msgmerge
+happens and then:
 
-### page titles
+        Use of uninitialized value $page in pattern match (m//) at /usr/local/share/perl/5.10.0/IkiWiki.pm line 624.
+        Use of uninitialized value $p in hash element at /usr/local/share/perl/5.10.0/IkiWiki/Render.pm line 423.
+        Use of uninitialized value $file in string eq at /usr/local/share/perl/5.10.0/IkiWiki/Render.pm line 444.
+        Use of uninitialized value $page in pattern match (m//) at /usr/local/share/perl/5.10.0/IkiWiki.pm line 624.
 
-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]].
+And then tons of:
+        Use of uninitialized value $page in pattern match (m//) at /usr/local/share/perl/5.10.0/IkiWiki.pm line 1860.
+        Use of uninitialized value $page in concatenation (.) or string at /usr/local/share/perl/5.10.0/IkiWiki.pm line 1869.
 
-### source files format
+Page titles in links
+--------------------
 
-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.
+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]].
+
+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.
+
+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 +509,15 @@ 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.
+
+Broken links
+------------
+
+See [[contrib/po]].
+
+Documentation
+-------------
+
+Maybe write separate documentation depending on the people it targets:
+translators, wiki administrators, hackers. This plugin is maybe
+complex enough to deserve this.