From d8c28006748ffe6037104bba4c040b2850cd8402 Mon Sep 17 00:00:00 2001
From: intrigeri <intrigeri@boum.org>
Date: Wed, 15 Oct 2008 01:25:01 +0200
Subject: [PATCH] po plugin: documented custom PageSpec tests, reorganized doc
 a bit

Signed-off-by: intrigeri <intrigeri@boum.org>
---
 doc/ikiwiki/pagespec/po.mdwn | 16 +++++++++
 doc/plugins/po.mdwn          | 65 ++++++++++++++++++------------------
 2 files changed, 48 insertions(+), 33 deletions(-)
 create mode 100644 doc/ikiwiki/pagespec/po.mdwn

diff --git a/doc/ikiwiki/pagespec/po.mdwn b/doc/ikiwiki/pagespec/po.mdwn
new file mode 100644
index 000000000..2edfaa0c1
--- /dev/null
+++ b/doc/ikiwiki/pagespec/po.mdwn
@@ -0,0 +1,16 @@
+[[!if test="enabled(po)"
+     then="This wiki has po support **enabled**."
+     else="This wiki has po support **disabled**."]]
+
+If the [[po|plugins/po]] plugin is enabled, the regular
+[[ikiwiki/PageSpec]] syntax is expanded with the following additional
+tests that can be used to improve user navigation in a multi-lingual
+wiki:
+
+* "`lang(LL)`" - Tests whether a page is written in the language
+  specified as a ISO639-1 (two-letter) language code.
+* "`currentlang()`" - Tests whether a page is written in the same
+  language as the current page.
+
+Note: every non-PO page is considered to be written in
+`po_master_language`, as specified in `ikiwiki.setup`.
diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 97981544d..64d22d34c 100644
--- a/doc/plugins/po.mdwn
+++ b/doc/plugins/po.mdwn
@@ -93,29 +93,6 @@ page's language, *i.e.*:
 - `foo/page.LL.html` if `usedirs` is disabled
 
 
-Templates
----------
-
-The `OTHERLANGUAGES` loop provides ways to display the existing
-translations and/or master page. 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">"
-	         class="is_master_<TMPL_VAR NAME="MASTER">">
-	      <TMPL_VAR NAME="LANGUAGE">
-	    </a>
-	    </li>
-	  </TMPL_LOOP>
-	  </ul>
-	</div>
-	</TMPL_IF>
-
-
 Server support
 ==============
 
@@ -143,6 +120,38 @@ lighttpd unfortunately does not support content negotiation.
  emulate this?
 
 
+Usage
+=====
+
+Templates
+---------
+
+The `OTHERLANGUAGES` loop provides ways to display the existing
+translations and/or master page. 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">"
+	         class="is_master_<TMPL_VAR NAME="MASTER">">
+	      <TMPL_VAR NAME="LANGUAGE">
+	    </a>
+	    </li>
+	  </TMPL_LOOP>
+	  </ul>
+	</div>
+	</TMPL_IF>
+
+Additional PageSpec tests
+-------------------------
+
+This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with some
+additional tests that are documented [[here|ikiwiki/pagespec/po]].
+
+
 TODO
 ====
 
@@ -199,16 +208,6 @@ page, to end up editing a strange looking PO file. The *Edit* button
 displayed on "slave" pages must therefore be renamed *Improve
 translation* .
 
-Pages selection depending on language
--------------------------------------
-
-To improve user navigation in a multi-lingual wiki, site developers
-must be enabled to write:
-
-        \[[!map pages="dev/* and lang(LL)" feeds="no"]]
-
-        \[[!map pages="dev/* and currentlang()" feeds="no"]]
-
 Translation quality assurance
 -----------------------------