po/todo: bug report about linking to subpages from translation pages

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

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 2f413e275c8aac3f1f1297819331004608598e5b..125a9b016ef1b5fef44c14c395d71c76b4bed897 100644 (file)
--- 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.
 
@@ -459,22 +463,49 @@ gettext/po4a rough corners
   into the Pot file, and let it propagate; should be fixed in
   `773de05a7a1ee68d2bed173367cf5e716884945a`, time will tell.
 
-Misc. improvements
-------------------
+Better links
+------------
+
+### Subpages
+
+On a translation page, links to subpages should actually be links to
+the master page's subpages. They currently appear as broken 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 +518,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.
+
+Creating new pages on the web
+-----------------------------
+
+See [[contrib/po]].
+
+Documentation
+-------------
+
+Maybe write separate documentation depending on the people it targets:
+translators, wiki administrators, hackers. This plugin may be complex
+enough to deserve this.