fix cherry-picked

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

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 235674f3167229be19c0deaa99d70f34b8461929..f020adac2e587ed516d767018e08db445f4a213b 100644 (file)
--- a/doc/plugins/po.mdwn
+++ b/doc/plugins/po.mdwn
@@ -55,7 +55,7 @@ Supported languages
 languages, such as:
 
         po_slave_languages => { 'fr' => 'Français',
 languages, such as:
 
         po_slave_languages => { 'fr' => 'Français',

-                                'es' => 'Castellano',
+                                'es' => 'Español',

                                 'de' => 'Deutsch',
         }
 
                                 'de' => 'Deutsch',
         }
 


@@ -114,7 +114,8 @@ Apache
 
 Using Apache `mod_negotiation` makes it really easy to have Apache
 serve any page in the client's preferred language, if available.
 
 Using Apache `mod_negotiation` makes it really easy to have Apache
 serve any page in the client's preferred language, if available.

-This is the default Debian Apache configuration.
+
+Add 'Options MultiViews' to the wiki directory's configuration in Apache.

 
 When `usedirs` is enabled, one has to set `DirectoryIndex index` for
 the wiki context.
 
 When `usedirs` is enabled, one has to set `DirectoryIndex index` for
 the wiki context.


@@ -123,6 +124,8 @@ Setting `DefaultLanguage LL` (replace `LL` with your default MIME
 language code) for the wiki context can help to ensure
 `bla/page/index.en.html` is served as `Content-Language: LL`.
 
 language code) for the wiki context can help to ensure
 `bla/page/index.en.html` is served as `Content-Language: LL`.
 

+For details, see [Apache's documentation](http://httpd.apache.org/docs/2.2/content-negotiation.html).
+

 lighttpd
 --------
 
 lighttpd
 --------
 


@@ -224,7 +227,7 @@ correctly on the slave pages:
 Security
 ========
 
 Security
 ========
 

-[[po/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
 and its dependencies.
 
 When using po4a older than 0.35, it is recommended to uninstall


@@ -248,43 +251,98 @@ ea753782b222bf4ba2fb4683b6363afdd9055b64, which should be reverted
 once [[intrigeri]]'s `meta` branch is merged.
 
 An integration branch, called `meta-po`, merges [[intrigeri]]'s `po`
 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.
+and `meta` branches, and thus has this additional features.
+
+Self links
+----------

 
 

-Robustness tests
-----------------
+If a page contains a WikiLink to itself, ikiwiki does not normally
+turn that into a hyperlink. However, if a translated page contains a
+WikiLink to itself, a hyperlink is inserted, at least with the default
+`po_link_to` the link points to the English version of the page. Is there a
+good reason for that to be done? --[[Joey]]

 
 

-### Enabling/disabling the plugin
+> The commit 0113c69d4fb in my po branch might fix this. --[[intrigeri]]

 
 

-* 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**
+>> It may fix it in passing, but shouldn't it also be fixed for the other
+>> `po_link_to` styles?

 
 

-### Changing the plugin config
+>>> Other `po_link_to` styles already work ok: say there is
+>>> a \[[dest]] link on a page called `dest`. When rendering
+>>> `dest.LL`, `mybestlink` returns `dest.LL`, and `htmllink` is then
+>>> able to detect, and manage correctly, that it is a self-link.
+>>> --[[intrigeri]]

 
 

-* 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)
+>> (Also, if `mybestlink` is going to always just return `bestlink` in
+>> this case, there seems no reason to inject it.) --[[Joey]]

 
 

-### Creating/deleting/renaming pages
+>>> Right. Commit cdc3576c8d1efb2 in my po branch prevents
+>>> `mybestlink` to be injected when `po_link_to` is
+>>> `default`. --[[intrigeri]]

 
 

-All cases of master/slave page creation/deletion/rename, both via RCS
-and via CGI, have been tested.
+Language display order
+----------------------

 
 

-### Misc
+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]] 

 
 

-* 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**
+Pagespecs
+---------

 
 

-Misc. bugs
-----------
+I was suprised that, when using the map directive, a pagespec of "*"
+listed all the translated pages as well as regular pages. That can 
+make a big difference to an existing wiki when po is turned on,
+and seems generally not wanted.
+(OTOH, you do want to match translated pages by
+default when locking pages.) --[[Joey]]
+
+Edit links on untranslated pages
+--------------------------------
+
+If a page is not translated yet, the "translated" version of it
+displays wikilinks to other, existing (but not yet translated?)
+pages as edit links, as if those pages do not exist. 
+
+That's really confusing, especially as clicking such a link
+brings up an edit form to create a new, english page.
+
+This is with po_link_to=current or negotiated. With default, it doesn't
+happen.. 
+
+Also, this may only happen if the page being linked to is coming from an
+underlay, and the underlays lack translation to a given language.
+--[[Joey]] 
+
+Double commits of po files
+--------------------------
+
+When adding a new english page, the po files are created, committed,
+and then committed again. The second commit makes this change:
+
+       -"Content-Type: text/plain; charset=utf-8\n"
+       -"Content-Transfer-Encoding: ENCODING"
+       +"Content-Type: text/plain; charset=UTF-8\n"
+       +"Content-Transfer-Encoding: ENCODING\n"
+
+Same thing happens when a change to an existing page triggers a po file
+update. --[[Joey]] 
+
+Ugly messages with empty files
+------------------------------
+
+If there are empty .mdwn files, the po plugin displays some ugly messages.
+
+Translation of directives
+-------------------------
+
+If a translated page contains a directive, it may expand to some english
+text, or text in whatever single language ikiwiki is configured to "speak".
+
+Maybe there could be a way to switch ikiwiki to speaking another language
+when building a non-english page? Then the directives would get translated.

 
 Documentation
 -------------
 
 Documentation
 -------------