Merge pull request #708 from splitbrain/overridablelangstrings

extend lang file cascade, so users can override some lang strings

6 files changed, 159 insertions, 89 deletions

diff --git a/inc/config_cascade.php b/inc/config_cascade.php
index 2c4f1612b..1d9f67edb 100644
--- a/inc/config_cascade.php
+++ b/inc/config_cascade.php
@@ -8,71 +8,75 @@
 $config_cascade = array_merge(
     array(
         'main' => array(
-            'default'   => array(DOKU_CONF.'dokuwiki.php'),
-            'local'     => array(DOKU_CONF.'local.php'),
-            'protected' => array(DOKU_CONF.'local.protected.php'),
-            ),
-        'acronyms'  => array(
-            'default'   => array(DOKU_CONF.'acronyms.conf'),
-            'local'     => array(DOKU_CONF.'acronyms.local.conf'),
-            ),
-        'entities'  => array(
-            'default'   => array(DOKU_CONF.'entities.conf'),
-            'local'     => array(DOKU_CONF.'entities.local.conf'),
-            ),
+            'default'   => array(DOKU_CONF . 'dokuwiki.php'),
+            'local'     => array(DOKU_CONF . 'local.php'),
+            'protected' => array(DOKU_CONF . 'local.protected.php'),
+        ),
+        'acronyms' => array(
+            'default'   => array(DOKU_CONF . 'acronyms.conf'),
+            'local'     => array(DOKU_CONF . 'acronyms.local.conf'),
+        ),
+        'entities' => array(
+            'default'   => array(DOKU_CONF . 'entities.conf'),
+            'local'     => array(DOKU_CONF . 'entities.local.conf'),
+        ),
         'interwiki' => array(
-            'default'   => array(DOKU_CONF.'interwiki.conf'),
-            'local'     => array(DOKU_CONF.'interwiki.local.conf'),
-            ),
+            'default'   => array(DOKU_CONF . 'interwiki.conf'),
+            'local'     => array(DOKU_CONF . 'interwiki.local.conf'),
+        ),
         'license' => array(
-            'default'   => array(DOKU_CONF.'license.php'),
-            'local'     => array(DOKU_CONF.'license.local.php'),
-            ),
+            'default'   => array(DOKU_CONF . 'license.php'),
+            'local'     => array(DOKU_CONF . 'license.local.php'),
+        ),
         'mediameta' => array(
-            'default'   => array(DOKU_CONF.'mediameta.php'),
-            'local'     => array(DOKU_CONF.'mediameta.local.php'),
-            ),
-        'mime'      => array(
-            'default'   => array(DOKU_CONF.'mime.conf'),
-            'local'     => array(DOKU_CONF.'mime.local.conf'),
-            ),
-        'scheme'    => array(
-            'default'   => array(DOKU_CONF.'scheme.conf'),
-            'local'     => array(DOKU_CONF.'scheme.local.conf'),
-            ),
-        'smileys'   => array(
-            'default'   => array(DOKU_CONF.'smileys.conf'),
-            'local'     => array(DOKU_CONF.'smileys.local.conf'),
-            ),
+            'default'   => array(DOKU_CONF . 'mediameta.php'),
+            'local'     => array(DOKU_CONF . 'mediameta.local.php'),
+        ),
+        'mime' => array(
+            'default'   => array(DOKU_CONF . 'mime.conf'),
+            'local'     => array(DOKU_CONF . 'mime.local.conf'),
+        ),
+        'scheme' => array(
+            'default'   => array(DOKU_CONF . 'scheme.conf'),
+            'local'     => array(DOKU_CONF . 'scheme.local.conf'),
+        ),
+        'smileys' => array(
+            'default'   => array(DOKU_CONF . 'smileys.conf'),
+            'local'     => array(DOKU_CONF . 'smileys.local.conf'),
+        ),
         'wordblock' => array(
-            'default'   => array(DOKU_CONF.'wordblock.conf'),
-            'local'     => array(DOKU_CONF.'wordblock.local.conf'),
-            ),
+            'default'   => array(DOKU_CONF . 'wordblock.conf'),
+            'local'     => array(DOKU_CONF . 'wordblock.local.conf'),
+        ),
         'userstyle' => array(
-            'screen'  => DOKU_CONF.'userstyle.css',
-            'print'   => DOKU_CONF.'userprint.css',
-            'feed'    => DOKU_CONF.'userfeed.css',
-            'all'     => DOKU_CONF.'userall.css',
-            ),
+            'screen'    => DOKU_CONF . 'userstyle.css',
+            'print'     => DOKU_CONF . 'userprint.css',
+            'feed'      => DOKU_CONF . 'userfeed.css',
+            'all'       => DOKU_CONF . 'userall.css',
+        ),
         'userscript' => array(
-            'default' => DOKU_CONF.'userscript.js'
-            ),
-        'acl'       => array(
-            'default'   => DOKU_CONF.'acl.auth.php',
-            ),
+            'default'   => DOKU_CONF . 'userscript.js'
+        ),
+        'acl' => array(
+            'default'   => DOKU_CONF . 'acl.auth.php',
+        ),
         'plainauth.users' => array(
-            'default' => DOKU_CONF.'users.auth.php',
-            ),
-
+            'default'   => DOKU_CONF . 'users.auth.php',
+        ),
         'plugins' => array(
-            'default'   => array(DOKU_CONF.'plugins.php'),
-            'local'     => array(DOKU_CONF.'plugins.local.php'),
+            'default'   => array(DOKU_CONF . 'plugins.php'),
+            'local'     => array(DOKU_CONF . 'plugins.local.php'),
             'protected' => array(
-                DOKU_CONF.'plugins.required.php',
-                DOKU_CONF.'plugins.protected.php',
-                ),
+                DOKU_CONF . 'plugins.required.php',
+                DOKU_CONF . 'plugins.protected.php',
             ),
         ),
-        $config_cascade
+        'lang' => array(
+            'core'      => array(DOKU_CONF . 'lang/'),
+            'plugin'    => array(DOKU_CONF . 'plugin_lang/'),
+            'template'  => array(DOKU_CONF . 'template_lang/')
+        )
+    ),
+    $config_cascade
 );
 
diff --git a/inc/init.php b/inc/init.php
index d825b5250..24920a17d 100644
--- a/inc/init.php
+++ b/inc/init.php
@@ -259,17 +259,33 @@ function init_paths(){
     $conf['media_changelog'] = $conf['metadir'].'/_media.changes';
 }
 
+/**
+ * Load the language strings
+ *
+ * @param string $langCode language code, as passed by event handler
+ */
 function init_lang($langCode) {
     //prepare language array
-    global $lang;
+    global $lang, $config_cascade;
     $lang = array();
 
     //load the language files
     require(DOKU_INC.'inc/lang/en/lang.php');
+    foreach ($config_cascade['lang']['core'] as $config_file) {
+        if (@file_exists($config_file . 'en/lang.php')) {
+            include($config_file . 'en/lang.php');
+        }
+    }
+
     if ($langCode && $langCode != 'en') {
         if (file_exists(DOKU_INC."inc/lang/$langCode/lang.php")) {
             require(DOKU_INC."inc/lang/$langCode/lang.php");
         }
+        foreach ($config_cascade['lang']['core'] as $config_file) {
+            if (@file_exists($config_file . "$langCode/lang.php")) {
+                include($config_file . "$langCode/lang.php");
+            }
+        }
     }
 }
 
diff --git a/inc/media.php b/inc/media.php
index 9022858e1..5190862d7 100644
--- a/inc/media.php
+++ b/inc/media.php
@@ -582,6 +582,12 @@ function media_notify($id,$file,$mime,$old_rev=false){
 
 /**
  * List all files in a given Media namespace
+ *
+ * @param string        $ns             namespace
+ * @param null|int      $auth           permission level
+ * @param string        $jump
+ * @param bool          $fullscreenview
+ * @param bool|string   $sort           sorting, false skips sorting
  */
 function media_filelist($ns,$auth=null,$jump='',$fullscreenview=false,$sort=false){
     global $conf;
diff --git a/inc/parserutils.php b/inc/parserutils.php
index 4aebec2c8..ba073f15d 100644
--- a/inc/parserutils.php
+++ b/inc/parserutils.php
@@ -640,6 +640,7 @@ function p_get_renderer($mode) {
     }
 
     // not bundled, see if its an enabled renderer plugin & when $mode is 'xhtml', the renderer can supply that format.
+    /** @var Doku_Renderer $Renderer */
     $Renderer = $plugin_controller->load('renderer',$rname);
     if ($Renderer && is_a($Renderer, 'Doku_Renderer')  && ($mode != 'xhtml' || $mode == $Renderer->getFormat())) {
         return $Renderer;
diff --git a/inc/plugin.php b/inc/plugin.php
index fbfc0325f..80689e389 100644
--- a/inc/plugin.php
+++ b/inc/plugin.php
@@ -30,7 +30,7 @@ class DokuWiki_Plugin {
      * desc   - Short description of the plugin (Text only)
      * url    - Website with more information on the plugin (eg. syntax description)
      */
-    function getInfo() {
+    public function getInfo(){
         $parts = explode('_', get_class($this));
         $info = DOKU_PLUGIN . '/' . $parts[2] . '/plugin.info.txt';
         if(@file_exists($info)) return confToHash($info);
@@ -48,16 +48,16 @@ class DokuWiki_Plugin {
 
     // plugin introspection methods
     // extract from class name, format = <plugin type>_plugin_<name>[_<component name>]
-    function getPluginType() {
+    public function getPluginType() {
         list($t) = explode('_', get_class($this), 2);
         return $t;
     }
-    function getPluginName() {
-        list($t, $p, $n) = explode('_', get_class($this), 4);
+    public function getPluginName() {
+        list(/* $t */, /* $p */, $n) = explode('_', get_class($this), 4);
         return $n;
     }
-    function getPluginComponent() {
-        list($t, $p, $n, $c) = explode('_', get_class($this), 4);
+    public function getPluginComponent() {
+        list(/* $t */, /* $p */, /* $n */, $c) = explode('_', get_class($this), 4);
         return (isset($c)?$c:'');
     }
 
@@ -71,7 +71,7 @@ class DokuWiki_Plugin {
      * @param   string  $id     id of the string to be retrieved
      * @return  string  string in appropriate language or english if not available
      */
-    function getLang($id) {
+    public function getLang($id) {
         if (!$this->localised) $this->setupLocale();
 
         return (isset($this->lang[$id]) ? $this->lang[$id] : '');
@@ -86,7 +86,7 @@ class DokuWiki_Plugin {
      * @param   string $id id of language dependent wiki page
      * @return  string     parsed contents of the wiki page in xhtml format
      */
-    function locale_xhtml($id) {
+    public function locale_xhtml($id) {
         return p_cached_output($this->localFN($id));
     }
 
@@ -95,7 +95,7 @@ class DokuWiki_Plugin {
      * prepends appropriate path for a language dependent filename
      * plugin equivalent of localFN()
      */
-    function localFN($id) {
+    public function localFN($id) {
         global $conf;
         $plugin = $this->getPluginName();
         $file = DOKU_CONF.'plugin_lang/'.$plugin.'/'.$conf['lang'].'/'.$id.'.txt';
@@ -115,16 +115,29 @@ class DokuWiki_Plugin {
      *  this function is automatically called by getLang()
      */
     function setupLocale() {
-        if ($this->localised) return;
+        if($this->localised) return;
 
-        global $conf;            // definitely don't invoke "global $lang"
-        $path = DOKU_PLUGIN.$this->getPluginName().'/lang/';
+        global $conf, $config_cascade; // definitely don't invoke "global $lang"
+        $path = DOKU_PLUGIN . $this->getPluginName() . '/lang/';
 
         $lang = array();
 
         // don't include once, in case several plugin components require the same language file
-        @include($path.'en/lang.php');
-        if ($conf['lang'] != 'en') @include($path.$conf['lang'].'/lang.php');
+        @include($path . 'en/lang.php');
+        foreach($config_cascade['lang']['plugin'] as $config_file) {
+            if(@file_exists($config_file . $this->getPluginName() . '/en/lang.php')) {
+                include($config_file . $this->getPluginName() . '/en/lang.php');
+            }
+        }
+
+        if($conf['lang'] != 'en') {
+            @include($path . $conf['lang'] . '/lang.php');
+            foreach($config_cascade['lang']['plugin'] as $config_file) {
+                if(@file_exists($config_file . $this->getPluginName() . '/' . $conf['lang'] . '/lang.php')) {
+                    include($config_file . $this->getPluginName() . '/' . $conf['lang'] . '/lang.php');
+                }
+            }
+        }
 
         $this->lang = $lang;
         $this->localised = true;
@@ -140,7 +153,7 @@ class DokuWiki_Plugin {
      * @param mixed  $notset  what to return if the setting is not available
      * @return mixed
      */
-    function getConf($setting, $notset=false){
+    public function getConf($setting, $notset=false){
 
         if (!$this->configloaded){ $this->loadConfig(); }
 
@@ -177,7 +190,7 @@ class DokuWiki_Plugin {
      *
      * @return    array    setting => value
      */
-    function readDefaultSettings() {
+    protected function readDefaultSettings() {
 
         $path = DOKU_PLUGIN.$this->getPluginName().'/conf/';
         $conf = array();
@@ -199,7 +212,7 @@ class DokuWiki_Plugin {
      *
      * @return  object  helper plugin object
      */
-    function loadHelper($name, $msg = true){
+    public function loadHelper($name, $msg = true){
         $obj = plugin_load('helper',$name);
         if (is_null($obj) && $msg) msg("Helper plugin $name is not available or invalid.",-1);
         return $obj;
@@ -212,7 +225,7 @@ class DokuWiki_Plugin {
      * email
      * standardised function to generate an email link according to obfuscation settings
      */
-    function email($email, $name='', $class='', $more='') {
+    public function email($email, $name='', $class='', $more='') {
         if (!$email) return $name;
         $email = obfuscate($email);
         if (!$name) $name = $email;
@@ -224,7 +237,7 @@ class DokuWiki_Plugin {
      * external_link
      * standardised function to generate an external link according to conf settings
      */
-    function external_link($link, $title='', $class='', $target='', $more='') {
+    public function external_link($link, $title='', $class='', $target='', $more='') {
         global $conf;
 
         $link = htmlentities($link);
@@ -251,7 +264,7 @@ class DokuWiki_Plugin {
      * @param $arguments
      * @return null|string
      */
-    function __call($name, $arguments) {
+    public function __call($name, $arguments) {
         if($name == 'render'){
             dbg_deprecated('render_text()');
             if(!isset($arguments[1])) $arguments[1] = 'xhtml';
@@ -269,7 +282,7 @@ class DokuWiki_Plugin {
      * @param string $format output format
      * @return null|string
      */
-    function render_text($text, $format='xhtml') {
+    public function render_text($text, $format='xhtml') {
         return p_render($format, p_get_instructions($text),$info);
     }
 
@@ -278,7 +291,7 @@ class DokuWiki_Plugin {
      *
      * @return bool   false if the plugin has to be instantiated
      */
-    function isSingleton() {
+    public function isSingleton() {
         return true;
     }
 }
diff --git a/inc/template.php b/inc/template.php
index 2dd77502f..31a65ce61 100644
--- a/inc/template.php
+++ b/inc/template.php
@@ -456,6 +456,12 @@ function _tpl_metaheaders_action($data) {
  * Just builds a link.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $url
+ * @param string $name
+ * @param string $more
+ * @param bool   $return if true return the link html, otherwise print
+ * @return bool|string html of the link, or true if printed
  */
 function tpl_link($url, $name, $more = '', $return = false) {
     $out = '<a href="'.$url.'" ';
@@ -472,6 +478,10 @@ function tpl_link($url, $name, $more = '', $return = false) {
  * Wrapper around html_wikilink
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string      $id   page id
+ * @param string|null $name link name
+ * @return bool true
  */
 function tpl_pagelink($id, $name = null) {
     print '<bdi>'.html_wikilink($id, $name).'</bdi>';
@@ -534,6 +544,13 @@ function tpl_button($type, $return = false) {
  *
  * @author Adrian Lang <mail@adrianlang.de>
  * @see    tpl_get_action
+ *
+ * @param string $type  action name
+ * @param string $pre   prefix of link
+ * @param string $suf   suffix of link
+ * @param string $inner inner HTML for link
+ * @param bool $return  if true it returns html, otherwise prints
+ * @return bool|string html of action link or false if nothing, or true if printed
  */
 function tpl_actionlink($type, $pre = '', $suf = '', $inner = '', $return = false) {
     global $lang;
@@ -571,7 +588,7 @@ function tpl_actionlink($type, $pre = '', $suf = '', $inner = '', $return = fals
             $linktarget, $pre.(($inner) ? $inner : $caption).$suf,
             'class="action '.$type.'" '.
                 $akey.$rel.
-                'title="'.hsc($caption).$addTitle.'"', 1
+                'title="'.hsc($caption).$addTitle.'"', true
         );
     }
     if($return) return $out;
@@ -747,7 +764,6 @@ function tpl_get_action($type) {
             break;
         default:
             return '[unknown %s type]';
-            break;
     }
     return compact('accesskey', 'type', 'id', 'method', 'params', 'nofollow', 'replacement');
 }
@@ -768,9 +784,9 @@ function tpl_get_action($type) {
 function tpl_action($type, $link = false, $wrapper = false, $return = false, $pre = '', $suf = '', $inner = '') {
     $out = '';
     if($link) {
-        $out .= tpl_actionlink($type, $pre, $suf, $inner, 1);
+        $out .= tpl_actionlink($type, $pre, $suf, $inner, true);
     } else {
-        $out .= tpl_button($type, 1);
+        $out .= tpl_button($type, true);
     }
     if($out && $wrapper) $out = "<$wrapper>$out</$wrapper>";
 
@@ -1027,7 +1043,7 @@ function tpl_pagetitle($id = null, $ret = false) {
  * Only allowed in: detail.php
  *
  * @author Andreas Gohr <andi@splitbrain.org>
- * @param array  $tags tags to try
+ * @param array|string  $tags tag or array of tags to try
  * @param string $alt alternative output if no data was found
  * @param null   $src the image src, uses global $SRC if not given
  * @return string
@@ -1275,16 +1291,29 @@ function tpl_getLang($id) {
     static $lang = array();
 
     if(count($lang) === 0) {
-        $path = tpl_incdir().'lang/';
+        global $conf, $config_cascade; // definitely don't invoke "global $lang"
+
+        $path = tpl_incdir() . 'lang/';
 
         $lang = array();
 
-        global $conf; // definitely don't invoke "global $lang"
         // don't include once
-        @include($path.'en/lang.php');
-        if($conf['lang'] != 'en') @include($path.$conf['lang'].'/lang.php');
-    }
+        @include($path . 'en/lang.php');
+        foreach($config_cascade['lang']['template'] as $config_file) {
+            if(@file_exists($config_file . $conf['template'] . '/en/lang.php')) {
+                include($config_file . $conf['template'] . '/en/lang.php');
+            }
+        }
 
+        if($conf['lang'] != 'en') {
+            @include($path . $conf['lang'] . '/lang.php');
+            foreach($config_cascade['lang']['template'] as $config_file) {
+                if(@file_exists($config_file . $conf['template'] . '/' . $conf['lang'] . '/lang.php')) {
+                    include($config_file . $conf['template'] . '/' . $conf['lang'] . '/lang.php');
+                }
+            }
+        }
+    }
     return $lang[$id];
 }
 
@@ -1305,7 +1334,7 @@ function tpl_locale_xhtml($id) {
 function tpl_localeFN($id) {
     $path = tpl_incdir().'lang/';
     global $conf;
-    $file = DOKU_CONF.'/template_lang/'.$conf['template'].'/'.$conf['lang'].'/'.$id.'.txt';
+    $file = DOKU_CONF.'template_lang/'.$conf['template'].'/'.$conf['lang'].'/'.$id.'.txt';
     if (!@file_exists($file)){
         $file = $path.$conf['lang'].'/'.$id.'.txt';
         if(!@file_exists($file)){
@@ -1327,6 +1356,7 @@ function tpl_localeFN($id) {
  *
  * @triggers MEDIAMANAGER_CONTENT_OUTPUT
  * @param bool $fromajax - set true when calling this function via ajax
+ * @param string $sort
  * @author Andreas Gohr <andi@splitbrain.org>
  */
 function tpl_mediaContent($fromajax = false, $sort='natural') {