po: s/utf-8/UTF-8, to solve part of the double commit bug.

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

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 1f57418b539c9f23476f886944d54eefc54e76cb..2e16cc7c457ae6f802938748da4edac628b4453c 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,14 +124,17 @@ 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
 --------
 

-lighttpd unfortunately does not support content negotiation.
+Recent versions of lighttpd should be able to use
+`$HTTP["language"]` to configure the translatted pages to be served.

 
 

-**FIXME**: does `mod_magnet` provide the functionality needed to
- emulate this?
+See [Lighttpd Issue](http://redmine.lighttpd.net/issues/show/1119)

 
 

+TODO: Example

 
 Usage
 =====
 
 Usage
 =====


@@ -150,24 +154,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.
 
 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
 
 * `URL` - url to the page
 * `CODE` - two-letters language code


@@ -178,15 +167,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
 ### 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
 -------------------------
 
 Additional PageSpec tests
 -------------------------


@@ -246,7 +228,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


@@ -270,43 +252,93 @@ 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.
+
+Language display order
+----------------------
+
+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]] 
+
+> Done in my po branch, preserving backward compatibility. Please
+> review :) --[[intrigeri]]
+
+Pagespecs
+---------
+
+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]]

 
 

-Robustness tests
-----------------
+Edit links on untranslated pages
+--------------------------------

 
 

-### Enabling/disabling the plugin
+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. 

 
 

-* 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**
+That's really confusing, especially as clicking such a link
+brings up an edit form to create a new, english page.

 
 

-### Changing the plugin config
+This is with po_link_to=current or negotiated. With default, it doesn't
+happen.. 

 
 

-* 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, 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]] 

 
 

-### Creating/deleting/renaming pages
+> Any simple testcase to reproduce it, please? I've never seen this
+> happen yet. --[[intrigeri]]

 
 

-All cases of master/slave page creation/deletion/rename, both via RCS
-and via CGI, have been tested.
+>> Sure, go here <http://l10n.ikiwiki.info/smiley/smileys/index.sv.html>
+>> (Currently 0% translateed) and see the 'WikiLink' link at the bottom,
+>> which goes to <http://l10n.ikiwiki.info/ikiwiki.cgi?page=ikiwiki/wikilink&from=smiley/smileys&do=create>
+>> Compare with eg, the 100% translated Dansk version, where
+>> the WikiLink link links to the English WikiLink page. --[[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]] 
+
+> * The s/utf-8/UTF-8 part is fixed in my po branch.
+> * The ENCODING\n part is due to an inconsistency in po4a, which
+>   I've just send a patch for. --[[intrigeri]]
+
+Ugly messages with empty files
+------------------------------
+
+If there are empty .mdwn files, the po plugin displays some ugly messages.
+
+> This is due to a bug in po4a (not checking definedness of a
+> variable). One-liner patch sent. --[[intrigeri]]
+
+Translation of directives
+-------------------------

 
 

-### Misc
+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".

 
 

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

 
 

-Misc. bugs
-----------
+(We also will need this in order to use translated templates, when they are
+available.)

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