X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/40de619d4968ecd7dc0086ca5118746bc3db3860..a7e5541c4d3f717811551d574af528236fa5f214:/doc/plugins/po.mdwn
diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 7165015ab..a0d3e7a93 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]]
@@ -53,7 +55,7 @@ Supported languages
languages, such as:
po_slave_languages => { 'fr' => 'Français',
- 'es' => 'Castellano',
+ 'es' => 'Español',
'de' => 'Deutsch',
}
@@ -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`:
-
-
-
-
-
- -
- ">
-
- ( %)
-
-
-
-
-
-
-
-
+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,49 +237,54 @@ 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.
-Robustness tests
-----------------
+An integration branch, called `meta-po`, merges [[intrigeri]]'s `po`
+and `meta` branches, and thus has thise additional features.
-### Enabling/disabling the plugin
-* enabling the plugin with `po_translatable_pages` set to blacklist: **OK**
-* enabling the plugin with `po_translatable_pages` set to whitelist: **OK**
-* enabling the plugin without `po_translatable_pages` set: **OK**
-* disabling the plugin: **OK**
+Language display order
+----------------------
-### Changing the plugin config
+Jonas pointed out that one might want to control the order that links to
+other languages are listed, for various reasons. Currently, there is no
+order, as `po_slave_languages` is a hash. It would need to be converted
+to an array to support this. (If twere done, twere best done quickly.)
+--[[Joey]]
-* 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)
+Re-render bug
+-------------
-### Creating/deleting/renaming pages
+If .ikiwiki is deleted and a wiki is rebuilt from scratch, and
+po has created po files before, something wrong happens:
-All cases of master/slave page creation/deletion/rename, both via RCS
-and via CGI, have been tested.
+> joey@gnu:~/src/ikiwiki/po/html>ls -l index*
+> -rw-r--r-- 1 joey joey 1159 Jul 19 22:51 index.html
+>
+> index.de:
+> total 4
+> -rw-r--r-- 1 joey joey 1829 Jul 19 22:51 index.html
-### Misc
+index.de/index.html contains the raw po file shoved into
+page.tmpl. I have only gotten as far as guessing it is a bug in
+`_istranslation` --[[Joey]]
-* general test with `usedirs` disabled: **OK**
-* general test with `indexpages` enabled: **not OK**
-* general test with `po_link_to=default` with `userdirs` enabled: **OK**
-* general test with `po_link_to=default` with `userdirs` disabled: **OK**
+Duplicate %links ?
+------------------
-Misc. bugs
-----------
+I notice code in the scan hook that seems to assume
+that %links will accumulate duplicate links for a page.
+That used to be so, but the bug was fixed. Does this mean
+that po might be replacing the only link on a page, in error?
+--[[Joey]]
Documentation
-------------