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

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 7165015ab..f19557a66 100644
--- a/doc/plugins/po.mdwn
+++ b/doc/plugins/po.mdwn
@@ -5,6 +5,8 @@ This plugin adds support for multi-lingual wikis, translated with
 gettext, using [po4a](http://po4a.alioth.debian.org/).
 
 It depends on the Perl `Locale::Po4a::Po` library (`apt-get install po4a`).
+As detailed bellow in the security section, `po4a` is subject to
+denial-of-service attacks before version 0.35.
 
 [[!toc levels=2]]
 
@@ -70,17 +72,19 @@ worry about excluding them explicitly from this [[ikiwiki/PageSpec]].
 Internal links
 --------------
 
+### Links targets
+
 The `po_link_to` option in `ikiwiki.setup` is used to decide how
 internal links should be generated, depending on web server features
 and site-specific preferences.
 
-### Default linking behavior
+#### Default linking behavior
 
 If `po_link_to` is unset, or set to `default`, ikiwiki's default
 linking behavior is preserved: `\[[destpage]]` links to the master
 language's page.
 
-### Link to current language
+#### Link to current language
 
 If `po_link_to` is set to `current`, `\[[destpage]]` links to the
 `destpage`'s version written in the current page's language, if
@@ -89,7 +93,7 @@ available, *i.e.*:
 * `foo/destpage/index.LL.html` if `usedirs` is enabled
 * `foo/destpage.LL.html` if `usedirs` is disabled
 
-### Link to negotiated language
+#### Link to negotiated language
 
 If `po_link_to` is set to `negotiated`, `\[[page]]` links to the
 negotiated preferred language, *i.e.* `foo/page/`.
@@ -102,7 +106,6 @@ negotiated preferred language, *i.e.* `foo/page/`.
 * if the web server does not support Content Negotiation, setting
   `po_link_to` to `negotiated` will produce a unusable website.
 
-
 Server support
 ==============
 
@@ -147,24 +150,9 @@ display things only on translatable or translation pages.
 The `OTHERLANGUAGES` loop provides ways to display other languages'
 versions of the same page, and the translations' status.
 
-One typically adds the following code to `templates/page.tmpl`:
-
-	<TMPL_IF NAME="OTHERLANGUAGES">
-	<div id="otherlanguages">
-	  <ul>
-	  <TMPL_LOOP NAME="OTHERLANGUAGES">
-	    <li>
-	      <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="LANGUAGE"></a>
-	      <TMPL_UNLESS NAME="MASTER">
-	        (<TMPL_VAR NAME="PERCENT">&nbsp;%)
-	      </TMPL_UNLESS>
-	    </li>
-	  </TMPL_LOOP>
-	  </ul>
-	</div>
-	</TMPL_IF>
-
-The following variables are available inside the loop (for every page in):
+An example of its use can be found in the default
+`templates/page.tmpl`. In case you want to customize it, the following
+variables are available inside the loop (for every page in):
 
 * `URL` - url to the page
 * `CODE` - two-letters language code
@@ -175,15 +163,8 @@ The following variables are available inside the loop (for every page in):
 ### Display the current translation status
 
 The `PERCENTTRANSLATED` variable is set to the translation
-completeness, expressed in percent, on "slave" pages.
-
-One can use it this way:
-
-	<TMPL_IF NAME="ISTRANSLATION">
-	<div id="percenttranslated">
-	  <TMPL_VAR NAME="PERCENTTRANSLATED">
-	</div>
-	</TMPL_IF>
+completeness, expressed in percent, on "slave" pages. It is used by
+the default `templates/page.tmpl`.
 
 Additional PageSpec tests
 -------------------------
@@ -228,8 +209,8 @@ 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
+[[Markdown|mdwn]] 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
@@ -243,7 +224,7 @@ correctly on the slave pages:
 Security
 ========
 
-[[./security]] contains a detailed security analysis of this plugin
+[[po/discussion]] contains a detailed security analysis of this plugin
 and its dependencies.
 
 When using po4a older than 0.35, it is recommended to uninstall
@@ -256,13 +237,18 @@ TODO
 Better links
 ------------
 
-### Page title in links
-
-Using the fix to
+Once 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 into ikiwiki upstream, though.
+[[intrigeri]]'s `meta` branch is merged into ikiwiki upstream, the
+generated links' text will be optionally based on the page titles set
+with the [[meta|plugins/meta]] plugin, and will thus be translatable.
+It will also allow displaying the translation status in links to slave
+pages. Both were implemented, and reverted in commit
+ea753782b222bf4ba2fb4683b6363afdd9055b64, which should be reverted
+once [[intrigeri]]'s `meta` branch is merged.
+
+An integration branch, called `meta-po`, merges [[intrigeri]]'s `po`
+and `meta` branches, and thus has thise additional features.
 
 Robustness tests
 ----------------