X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/b19d0d3d245c7c2b605ac6c972c73c909a941db4..a8105f68590c7aa56fc37ec62df854546a119060:/doc/plugins/po.mdwn?ds=sidebyside

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index eeeabe730..5337a2ce2 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
 ====
 
@@ -499,63 +519,77 @@ gettext/po4a rough corners
 Better links
 ------------
 
-### Subpages
+### Page title in links
+
+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.
 
-On a translation page, links to subpages should actually be links to
-the master page's subpages. They currently appear as broken links.
+Translation quality assurance
+-----------------------------
 
-### Page title in links
+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.
 
-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]].
+A new `cansave` type of hook would be needed to implement this.
 
-Going to work on this in my `meta` branch.
+Note: committing to the underlying repository is a way to bypass
+this check.
 
-### Translation status in links
+Creating new pages on the web
+-----------------------------
 
-See [[contrib/po]].
+See [[contrib/po|contrib/po]].
 
-### Backlinks
+Robustness tests
+----------------
 
-They are not updated when the source page changes (e.g. meta title).
+### Disabling the plugin
 
-Page formats
-------------
+- enabling the plugin with `po_translatable_pages` set
+- enabling the plugin without `po_translatable_pages` set: **OK**
+- disabling the plugin: **OK**
 
-Markdown is well supported, great, but what about others?
+### Changing the plugin config
 
-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.
+- 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)
 
-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.
+### Creating pages
 
-**TODO**: test the more popular formats and write proper documentation
-about it.
+- creating a master page via RCS: **OK**
+- creating a master page via CGI: **OK**
 
-Translation quality assurance
------------------------------
+### Deleting pages
 
-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.
+- removing a master page via RCS: **OK**
+- removing a translation via RCS: **OK**
+- removing a master page via CGI: **OK**
+- removing a translation via CGI: **OK**
 
-A new `cansave` type of hook would be needed to implement this.
+### Renaming pages
 
-Note: committing to the underlying repository is a way to bypass
-this check.
+- renaming a master page via RCS: **OK** (but the old translations
+  are lost, because not all RCS track file renaming)
+- renaming a master page and its translations via RCS: **OK**
+- renaming a master page via CGI: **OK**
+- renaming a translation via RCS
+- renaming a translation via CGI
 
-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
 -------------