Merge branch 'master' into stable

* master: (214 commits)
  release preparations
  postgresql auth plugin: correct function name
  parse AT parameter: first strtotime then timestamp remove config option
  move more strings to lang.php
  move strings to lang.php
  add placeholders for create page text
  phpdocs parserutils
  improve some scrutinizer issues
  visibility plugin methods
  use config cascade for loading of localizations
  reformatting config cascade
  add lang files to cascading
  work around missing gzopen on certain systems #865
  translation update
  fix scrutinizer issues
  fixed typos in docblock comments
  do not allow empty passwords
  clean user credentials from control chars
  added filter method to INPUT class
  translation update
  ...

1 files changed, 626 insertions, 139 deletions

diff --git a/inc/parser/renderer.php b/inc/parser/renderer.php
index e92b81bd7..09294539e 100644
--- a/inc/parser/renderer.php
+++ b/inc/parser/renderer.php
@@ -11,263 +11,748 @@ if(!defined('DOKU_INC')) die('meh.');
  * An empty renderer, produces no output
  *
  * Inherits from DokuWiki_Plugin for giving additional functions to render plugins
+ *
+ * The renderer transforms the syntax instructions created by the parser and handler into the
+ * desired output format. For each instruction a corresponding method defined in this class will
+ * be called. That method needs to produce the desired output for the instruction and add it to the
+ * $doc field. When all instructions are processed, the $doc field contents will be cached by
+ * DokuWiki and sent to the user.
  */
 class Doku_Renderer extends DokuWiki_Plugin {
-    var $info = array(
+    /** @var array Settings, control the behavior of the renderer */
+    public $info = array(
         'cache' => true, // may the rendered result cached?
         'toc'   => true, // render the TOC?
     );
 
-    var $doc = '';
+    /** @var array contains the smiley configuration, set in p_render() */
+    public $smileys = array();
+    /** @var array contains the entity configuration, set in p_render() */
+    public $entities = array();
+    /** @var array contains the acronym configuration, set in p_render() */
+    public $acronyms = array();
+    /** @var array contains the interwiki configuration, set in p_render() */
+    public $interwiki = array();
 
-    // keep some config options
-    var $acronyms = array();
-    var $smileys = array();
-    var $badwords = array();
-    var $entities = array();
-    var $interwiki = array();
+    /**
+     * @var string the rendered document, this will be cached after the renderer ran through
+     */
+    public $doc = '';
 
-    // allows renderer to be used again, clean out any per-use values
+    /**
+     * clean out any per-use values
+     *
+     * This is called before each use of the renderer object and should be used to
+     * completely reset the state of the renderer to be reused for a new document
+     */
     function reset() {
     }
 
-    function nocache() {
-        $this->info['cache'] = false;
-    }
-
-    function notoc() {
-        $this->info['toc'] = false;
+    /**
+     * Allow the plugin to prevent DokuWiki from reusing an instance
+     *
+     * Since most renderer plugins fail to implement Doku_Renderer::reset() we default
+     * to reinstantiating the renderer here
+     *
+     * @return bool   false if the plugin has to be instantiated
+     */
+    function isSingleton() {
+        return false;
     }
 
     /**
      * Returns the format produced by this renderer.
      *
-     * Has to be overidden by decendend classes
+     * Has to be overidden by sub classes
+     *
+     * @return string
      */
-    function getFormat(){
+    function getFormat() {
         trigger_error('getFormat() not implemented in '.get_class($this), E_USER_WARNING);
+        return '';
     }
 
     /**
-     * Allow the plugin to prevent DokuWiki from reusing an instance
+     * Disable caching of this renderer's output
+     */
+    function nocache() {
+        $this->info['cache'] = false;
+    }
+
+    /**
+     * Disable TOC generation for this renderer's output
      *
-     * @return bool   false if the plugin has to be instantiated
+     * This might not be used for certain sub renderer
      */
-    function isSingleton() {
-        return false;
+    function notoc() {
+        $this->info['toc'] = false;
     }
 
     /**
-     * handle plugin rendering
+     * Handle plugin rendering
+     *
+     * Most likely this needs NOT to be overwritten by sub classes
      *
-     * @param string $name Plugin name
-     * @param mixed  $data custom data set by handler
+     * @param string $name  Plugin name
+     * @param mixed  $data  custom data set by handler
      * @param string $state matched state if any
      * @param string $match raw matched syntax
      */
-    function plugin($name,$data,$state='',$match=''){
-        $plugin = plugin_load('syntax',$name);
-        if($plugin != null){
-            $plugin->render($this->getFormat(),$this,$data);
+    function plugin($name, $data, $state = '', $match = '') {
+        /** @var DokuWiki_Syntax_Plugin $plugin */
+        $plugin = plugin_load('syntax', $name);
+        if($plugin != null) {
+            $plugin->render($this->getFormat(), $this, $data);
         }
     }
 
     /**
      * handle nested render instructions
      * this method (and nest_close method) should not be overloaded in actual renderer output classes
+     *
+     * @param array $instructions
      */
     function nest($instructions) {
-
-        foreach ( $instructions as $instruction ) {
+        foreach($instructions as $instruction) {
             // execute the callback against ourself
-            if (method_exists($this,$instruction[0])) {
+            if(method_exists($this, $instruction[0])) {
                 call_user_func_array(array($this, $instruction[0]), $instruction[1] ? $instruction[1] : array());
             }
         }
     }
 
-    // dummy closing instruction issued by Doku_Handler_Nest, normally the syntax mode should
-    // override this instruction when instantiating Doku_Handler_Nest - however plugins will not
-    // be able to - as their instructions require data.
-    function nest_close() {}
-
-    function document_start() {}
+    /**
+     * dummy closing instruction issued by Doku_Handler_Nest
+     *
+     * normally the syntax mode should override this instruction when instantiating Doku_Handler_Nest -
+     * however plugins will not be able to - as their instructions require data.
+     */
+    function nest_close() {
+    }
 
-    function document_end() {}
+    #region Syntax modes - sub classes will need to implement them to fill $doc
 
-    function render_TOC() { return ''; }
+    /**
+     * Initialize the document
+     */
+    function document_start() {
+    }
 
-    function toc_additem($id, $text, $level) {}
+    /**
+     * Finalize the document
+     */
+    function document_end() {
+    }
 
-    function header($text, $level, $pos) {}
+    /**
+     * Render the Table of Contents
+     *
+     * @return string
+     */
+    function render_TOC() {
+        return '';
+    }
 
-    function section_open($level) {}
+    /**
+     * Add an item to the TOC
+     *
+     * @param string $id       the hash link
+     * @param string $text     the text to display
+     * @param int    $level    the nesting level
+     */
+    function toc_additem($id, $text, $level) {
+    }
 
-    function section_close() {}
+    /**
+     * Render a heading
+     *
+     * @param string $text  the text to display
+     * @param int    $level header level
+     * @param int    $pos   byte position in the original source
+     */
+    function header($text, $level, $pos) {
+    }
 
-    function cdata($text) {}
+    /**
+     * Open a new section
+     *
+     * @param int $level section level (as determined by the previous header)
+     */
+    function section_open($level) {
+    }
 
-    function p_open() {}
+    /**
+     * Close the current section
+     */
+    function section_close() {
+    }
 
-    function p_close() {}
+    /**
+     * Render plain text data
+     *
+     * @param $text
+     */
+    function cdata($text) {
+    }
 
-    function linebreak() {}
+    /**
+     * Open a paragraph
+     */
+    function p_open() {
+    }
 
-    function hr() {}
+    /**
+     * Close a paragraph
+     */
+    function p_close() {
+    }
 
-    function strong_open() {}
+    /**
+     * Create a line break
+     */
+    function linebreak() {
+    }
 
-    function strong_close() {}
+    /**
+     * Create a horizontal line
+     */
+    function hr() {
+    }
 
-    function emphasis_open() {}
+    /**
+     * Start strong (bold) formatting
+     */
+    function strong_open() {
+    }
 
-    function emphasis_close() {}
+    /**
+     * Stop strong (bold) formatting
+     */
+    function strong_close() {
+    }
 
-    function underline_open() {}
+    /**
+     * Start emphasis (italics) formatting
+     */
+    function emphasis_open() {
+    }
 
-    function underline_close() {}
+    /**
+     * Stop emphasis (italics) formatting
+     */
+    function emphasis_close() {
+    }
 
-    function monospace_open() {}
+    /**
+     * Start underline formatting
+     */
+    function underline_open() {
+    }
 
-    function monospace_close() {}
+    /**
+     * Stop underline formatting
+     */
+    function underline_close() {
+    }
 
-    function subscript_open() {}
+    /**
+     * Start monospace formatting
+     */
+    function monospace_open() {
+    }
 
-    function subscript_close() {}
+    /**
+     * Stop monospace formatting
+     */
+    function monospace_close() {
+    }
 
-    function superscript_open() {}
+    /**
+     * Start a subscript
+     */
+    function subscript_open() {
+    }
 
-    function superscript_close() {}
+    /**
+     * Stop a subscript
+     */
+    function subscript_close() {
+    }
 
-    function deleted_open() {}
+    /**
+     * Start a superscript
+     */
+    function superscript_open() {
+    }
 
-    function deleted_close() {}
+    /**
+     * Stop a superscript
+     */
+    function superscript_close() {
+    }
 
-    function footnote_open() {}
+    /**
+     * Start deleted (strike-through) formatting
+     */
+    function deleted_open() {
+    }
 
-    function footnote_close() {}
+    /**
+     * Stop deleted (strike-through) formatting
+     */
+    function deleted_close() {
+    }
 
-    function listu_open() {}
+    /**
+     * Start a footnote
+     */
+    function footnote_open() {
+    }
 
-    function listu_close() {}
+    /**
+     * Stop a footnote
+     */
+    function footnote_close() {
+    }
 
-    function listo_open() {}
+    /**
+     * Open an unordered list
+     */
+    function listu_open() {
+    }
 
-    function listo_close() {}
+    /**
+     * Close an unordered list
+     */
+    function listu_close() {
+    }
 
-    function listitem_open($level) {}
+    /**
+     * Open an ordered list
+     */
+    function listo_open() {
+    }
 
-    function listitem_close() {}
+    /**
+     * Close an ordered list
+     */
+    function listo_close() {
+    }
 
-    function listcontent_open() {}
+    /**
+     * Open a list item
+     *
+     * @param int $level the nesting level
+     */
+    function listitem_open($level) {
+    }
 
-    function listcontent_close() {}
+    /**
+     * Close a list item
+     */
+    function listitem_close() {
+    }
 
-    function unformatted($text) {}
+    /**
+     * Start the content of a list item
+     */
+    function listcontent_open() {
+    }
 
-    function php($text) {}
+    /**
+     * Stop the content of a list item
+     */
+    function listcontent_close() {
+    }
 
-    function phpblock($text) {}
+    /**
+     * Output unformatted $text
+     *
+     * Defaults to $this->cdata()
+     *
+     * @param string $text
+     */
+    function unformatted($text) {
+        $this->cdata($text);
+    }
 
-    function html($text) {}
+    /**
+     * Output inline PHP code
+     *
+     * If $conf['phpok'] is true this should evaluate the given code and append the result
+     * to $doc
+     *
+     * @param string $text The PHP code
+     */
+    function php($text) {
+    }
 
-    function htmlblock($text) {}
+    /**
+     * Output block level PHP code
+     *
+     * If $conf['phpok'] is true this should evaluate the given code and append the result
+     * to $doc
+     *
+     * @param string $text The PHP code
+     */
+    function phpblock($text) {
+    }
 
-    function preformatted($text) {}
+    /**
+     * Output raw inline HTML
+     *
+     * If $conf['htmlok'] is true this should add the code as is to $doc
+     *
+     * @param string $text The HTML
+     */
+    function html($text) {
+    }
 
-    function quote_open() {}
+    /**
+     * Output raw block-level HTML
+     *
+     * If $conf['htmlok'] is true this should add the code as is to $doc
+     *
+     * @param string $text The HTML
+     */
+    function htmlblock($text) {
+    }
 
-    function quote_close() {}
+    /**
+     * Output preformatted text
+     *
+     * @param string $text
+     */
+    function preformatted($text) {
+    }
 
-    function file($text, $lang = null, $file = null ) {}
+    /**
+     * Start a block quote
+     */
+    function quote_open() {
+    }
 
-    function code($text, $lang = null, $file = null ) {}
+    /**
+     * Stop a block quote
+     */
+    function quote_close() {
+    }
 
-    function acronym($acronym) {}
+    /**
+     * Display text as file content, optionally syntax highlighted
+     *
+     * @param string $text text to show
+     * @param string $lang programming language to use for syntax highlighting
+     * @param string $file file path label
+     */
+    function file($text, $lang = null, $file = null) {
+    }
 
-    function smiley($smiley) {}
+    /**
+     * Display text as code content, optionally syntax highlighted
+     *
+     * @param string $text text to show
+     * @param string $lang programming language to use for syntax highlighting
+     * @param string $file file path label
+     */
+    function code($text, $lang = null, $file = null) {
+    }
 
-    function wordblock($word) {}
+    /**
+     * Format an acronym
+     *
+     * Uses $this->acronyms
+     *
+     * @param string $acronym
+     */
+    function acronym($acronym) {
+    }
 
-    function entity($entity) {}
+    /**
+     * Format a smiley
+     *
+     * Uses $this->smiley
+     *
+     * @param string $smiley
+     */
+    function smiley($smiley) {
+    }
 
-    // 640x480 ($x=640, $y=480)
-    function multiplyentity($x, $y) {}
+    /**
+     * Format an entity
+     *
+     * Entities are basically small text replacements
+     *
+     * Uses $this->entities
+     *
+     * @param string $entity
+     */
+    function entity($entity) {
+    }
 
-    function singlequoteopening() {}
+    /**
+     * Typographically format a multiply sign
+     *
+     * Example: ($x=640, $y=480) should result in "640×480"
+     *
+     * @param string|int $x first value
+     * @param string|int $y second value
+     */
+    function multiplyentity($x, $y) {
+    }
 
-    function singlequoteclosing() {}
+    /**
+     * Render an opening single quote char (language specific)
+     */
+    function singlequoteopening() {
+    }
 
-    function apostrophe() {}
+    /**
+     * Render a closing single quote char (language specific)
+     */
+    function singlequoteclosing() {
+    }
 
-    function doublequoteopening() {}
+    /**
+     * Render an apostrophe char (language specific)
+     */
+    function apostrophe() {
+    }
 
-    function doublequoteclosing() {}
+    /**
+     * Render an opening double quote char (language specific)
+     */
+    function doublequoteopening() {
+    }
 
-    // $link like 'SomePage'
-    function camelcaselink($link) {}
+    /**
+     * Render an closinging double quote char (language specific)
+     */
+    function doublequoteclosing() {
+    }
 
-    function locallink($hash, $name = null) {}
+    /**
+     * Render a CamelCase link
+     *
+     * @param string $link The link name
+     * @see http://en.wikipedia.org/wiki/CamelCase
+     */
+    function camelcaselink($link) {
+    }
 
-    // $link like 'wiki:syntax', $title could be an array (media)
-    function internallink($link, $title = null) {}
+    /**
+     * Render a page local link
+     *
+     * @param string $hash hash link identifier
+     * @param string $name name for the link
+     */
+    function locallink($hash, $name = null) {
+    }
 
-    // $link is full URL with scheme, $title could be an array (media)
-    function externallink($link, $title = null) {}
+    /**
+     * Render a wiki internal link
+     *
+     * @param string       $link  page ID to link to. eg. 'wiki:syntax'
+     * @param string|array $title name for the link, array for media file
+     */
+    function internallink($link, $title = null) {
+    }
 
-    function rss ($url,$params) {}
+    /**
+     * Render an external link
+     *
+     * @param string       $link  full URL with scheme
+     * @param string|array $title name for the link, array for media file
+     */
+    function externallink($link, $title = null) {
+    }
 
-    // $link is the original link - probably not much use
-    // $wikiName is an indentifier for the wiki
-    // $wikiUri is the URL fragment to append to some known URL
-    function interwikilink($link, $title = null, $wikiName, $wikiUri) {}
+    /**
+     * Render the output of an RSS feed
+     *
+     * @param string $url    URL of the feed
+     * @param array  $params Finetuning of the output
+     */
+    function rss($url, $params) {
+    }
 
-    // Link to file on users OS, $title could be an array (media)
-    function filelink($link, $title = null) {}
+    /**
+     * Render an interwiki link
+     *
+     * You may want to use $this->_resolveInterWiki() here
+     *
+     * @param string       $link     original link - probably not much use
+     * @param string|array $title    name for the link, array for media file
+     * @param string       $wikiName indentifier (shortcut) for the remote wiki
+     * @param string       $wikiUri  the fragment parsed from the original link
+     */
+    function interwikilink($link, $title = null, $wikiName, $wikiUri) {
+    }
 
-    // Link to a Windows share, , $title could be an array (media)
-    function windowssharelink($link, $title = null) {}
+    /**
+     * Link to file on users OS
+     *
+     * @param string       $link  the link
+     * @param string|array $title name for the link, array for media file
+     */
+    function filelink($link, $title = null) {
+    }
 
-//  function email($address, $title = null) {}
-    function emaillink($address, $name = null) {}
+    /**
+     * Link to windows share
+     *
+     * @param string       $link  the link
+     * @param string|array $title name for the link, array for media file
+     */
+    function windowssharelink($link, $title = null) {
+    }
 
-    function internalmedia ($src, $title=null, $align=null, $width=null,
-                            $height=null, $cache=null, $linking=null) {}
+    /**
+     * Render a linked E-Mail Address
+     *
+     * Should honor $conf['mailguard'] setting
+     *
+     * @param string $address Email-Address
+     * @param string|array $name name for the link, array for media file
+     */
+    function emaillink($address, $name = null) {
+    }
 
-    function externalmedia ($src, $title=null, $align=null, $width=null,
-                            $height=null, $cache=null, $linking=null) {}
+    /**
+     * Render an internal media file
+     *
+     * @param string $src     media ID
+     * @param string $title   descriptive text
+     * @param string $align   left|center|right
+     * @param int    $width   width of media in pixel
+     * @param int    $height  height of media in pixel
+     * @param string $cache   cache|recache|nocache
+     * @param string $linking linkonly|detail|nolink
+     */
+    function internalmedia($src, $title = null, $align = null, $width = null,
+                           $height = null, $cache = null, $linking = null) {
+    }
 
-    function internalmedialink (
-        $src,$title=null,$align=null,$width=null,$height=null,$cache=null
-        ) {}
+    /**
+     * Render an external media file
+     *
+     * @param string $src     full media URL
+     * @param string $title   descriptive text
+     * @param string $align   left|center|right
+     * @param int    $width   width of media in pixel
+     * @param int    $height  height of media in pixel
+     * @param string $cache   cache|recache|nocache
+     * @param string $linking linkonly|detail|nolink
+     */
+    function externalmedia($src, $title = null, $align = null, $width = null,
+                           $height = null, $cache = null, $linking = null) {
+    }
 
-    function externalmedialink(
-        $src,$title=null,$align=null,$width=null,$height=null,$cache=null
-        ) {}
+    /**
+     * Render a link to an internal media file
+     *
+     * @param string $src     media ID
+     * @param string $title   descriptive text
+     * @param string $align   left|center|right
+     * @param int    $width   width of media in pixel
+     * @param int    $height  height of media in pixel
+     * @param string $cache   cache|recache|nocache
+     */
+    function internalmedialink($src, $title = null, $align = null,
+                               $width = null, $height = null, $cache = null) {
+    }
 
-    function table_open($maxcols = null, $numrows = null, $pos = null){}
+    /**
+     * Render a link to an external media file
+     *
+     * @param string $src     media ID
+     * @param string $title   descriptive text
+     * @param string $align   left|center|right
+     * @param int    $width   width of media in pixel
+     * @param int    $height  height of media in pixel
+     * @param string $cache   cache|recache|nocache
+     */
+    function externalmedialink($src, $title = null, $align = null,
+                               $width = null, $height = null, $cache = null) {
+    }
 
-    function table_close($pos = null){}
+    /**
+     * Start a table
+     *
+     * @param int $maxcols maximum number of columns
+     * @param int $numrows NOT IMPLEMENTED
+     * @param int $pos     byte position in the original source
+     */
+    function table_open($maxcols = null, $numrows = null, $pos = null) {
+    }
 
-    function tablethead_open(){}
+    /**
+     * Close a table
+     *
+     * @param int $pos byte position in the original source
+     */
+    function table_close($pos = null) {
+    }
 
-    function tablethead_close(){}
+    /**
+     * Open a table header
+     */
+    function tablethead_open() {
+    }
 
-    function tablerow_open(){}
+    /**
+     * Close a table header
+     */
+    function tablethead_close() {
+    }
 
-    function tablerow_close(){}
+    /**
+     * Open a table row
+     */
+    function tablerow_open() {
+    }
 
-    function tableheader_open($colspan = 1, $align = null, $rowspan = 1){}
+    /**
+     * Close a table row
+     */
+    function tablerow_close() {
+    }
 
-    function tableheader_close(){}
+    /**
+     * Open a table header cell
+     *
+     * @param int    $colspan
+     * @param string $align left|center|right
+     * @param int    $rowspan
+     */
+    function tableheader_open($colspan = 1, $align = null, $rowspan = 1) {
+    }
 
-    function tablecell_open($colspan = 1, $align = null, $rowspan = 1){}
+    /**
+     * Close a table header cell
+     */
+    function tableheader_close() {
+    }
 
-    function tablecell_close(){}
+    /**
+     * Open a table cell
+     *
+     * @param int    $colspan
+     * @param string $align left|center|right
+     * @param int    $rowspan
+     */
+    function tablecell_open($colspan = 1, $align = null, $rowspan = 1) {
+    }
 
+    /**
+     * Close a table cell
+     */
+    function tablecell_close() {
+    }
 
-    // util functions follow, you probably won't need to reimplement them
+    #endregion
 
+    #region util functions, you probably won't need to reimplement them
 
     /**
      * Removes any Namespace from the given name but keeps
@@ -294,13 +779,13 @@ class Doku_Renderer extends DokuWiki_Plugin {
     /**
      * Resolve an interwikilink
      */
-    function _resolveInterWiki(&$shortcut, $reference, &$exists=null) {
+    function _resolveInterWiki(&$shortcut, $reference, &$exists = null) {
         //get interwiki URL
         if(isset($this->interwiki[$shortcut])) {
             $url = $this->interwiki[$shortcut];
         } else {
             // Default to Google I'm feeling lucky
-            $url = 'http://www.google.com/search?q={URL}&btnI=lucky';
+            $url      = 'http://www.google.com/search?q={URL}&btnI=lucky';
             $shortcut = 'go';
         }
 
@@ -310,8 +795,8 @@ class Doku_Renderer extends DokuWiki_Plugin {
         //replace placeholder
         if(preg_match('#\{(URL|NAME|SCHEME|HOST|PORT|PATH|QUERY)\}#', $url)) {
             //use placeholders
-            $url = str_replace('{URL}', rawurlencode($reference), $url);
-            $url = str_replace('{NAME}', $reference, $url);
+            $url    = str_replace('{URL}', rawurlencode($reference), $url);
+            $url    = str_replace('{NAME}', $reference, $url);
             $parsed = parse_url($reference);
             if(!$parsed['port']) $parsed['port'] = 80;
             $url = str_replace('{SCHEME}', $parsed['scheme'], $url);
@@ -321,18 +806,20 @@ class Doku_Renderer extends DokuWiki_Plugin {
             $url = str_replace('{QUERY}', $parsed['query'], $url);
         } else {
             //default
-            $url = $url . rawurlencode($reference);
+            $url = $url.rawurlencode($reference);
         }
         //handle as wiki links
         if($url{0} === ':') {
             list($id, $urlparam) = explode('?', $url, 2);
-            $url = wl(cleanID($id), $urlparam);
+            $url    = wl(cleanID($id), $urlparam);
             $exists = page_exists($id);
         }
-        if($hash) $url .= '#' . rawurlencode($hash);
+        if($hash) $url .= '#'.rawurlencode($hash);
 
         return $url;
     }
+
+    #endregion
 }