====== outdent Plugin ======

---- plugin ----
description: Backout of section indenting (without using an empty header)
author     : Christopher Smith
email      : chris@jalakai.co.uk
type       : syntax
lastupdate : 2008-08-13
compatible : Binky
depends    :
conflicts  :
similar    :
tags       : section, headings

downloadurl: http://dokuwiki.jalakai.co.uk/plugin-outdent.zip
----

This plugin extends DokuWiki syntax to enable the removal of one level of section indenting.

In native [[:DokuWiki]], all the content between headings is included in a section. The indentation for a particular section corresponds to the heading it follows. DokuWiki doesn't provide a way to finish a section and move back to the indentation level of the previous section - at least not without using another heading.  This plugin makes that possible.

e.g.
  HEADING 1
  ==level 1 section content
    HEADING 2
    level 2 section content
      HEADING 3
      level 3 section content
    level 2 section content
      HEADING 3
  level 1 section content



===== Syntax =====

<file>
==
</file>
The two equals signs must be on their own line.

See the page in action [[http://wiki.jalakai.co.uk/dokuwiki/doku.php/test/outdent|here]]


===== Installation =====
Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

Plugin sources: [[http://dokuwiki.jalakai.co.uk/plugin-outdent.zip|zip format (2k)]], [[http://dokuwiki.jalakai.co.uk/plugin-outdent.tar.gz|tar.gz format (1k)]], [[http://wiki.jalakai.co.uk/repo/dokuwiki/plugins/outdent|darcs repository]]


===== Configuration =====

The plugin has no configuration settings.

===== Details =====

The plugin consists one file, the plugin script [[#syntax.php]].

==== syntax.php ====

<code php>
<?php
/**
 * Plugin Outdent: Removes one level of indenting.
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Christopher Smith <chris@jalakai.co.uk>
 */

if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');

/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_outdent extends DokuWiki_Syntax_Plugin {

    function getInfo(){
      return array(
        'author' => 'Christopher Smith',
        'email'  => 'chris@jalakai.co.uk',
        'date'   => '2008-08-13',
        'name'   => 'Outdent Plugin',
        'desc'   => 'Remove one level of indenting
                     Syntax: ==',
        'url'    => 'http://wiki.splitbrain.org/plugin:outdent',
      );
    }

    function getType() { return 'baseonly'; }
    function getSort() { return 50; }                       /* same as header */

    function connectTo($mode) {
        $this->Lexer->addSpecialPattern('\n[ \t]*==[ \t]*(?=\n)',$mode,'plugin_outdent');
    }

    function handle($match, $state, $pos, &$handler){
      $level=0;
      if ($state == DOKU_LEXER_SPECIAL) {
        $level = $this->_getLevel($handler->calls);
        if ($level > 1) {
            $handler->_addCall('section_close', array(), $pos);
            $handler->_addCall('section_open', array($level-1), $pos);
        }
      }

      return false;
    }

    function render($mode, &$renderer, $data) {

      return false;
    }

    function _getLevel(&$calls) {

      for ($i=count($calls); $i >= 0; $i--) {
          if ($calls[$i][0] == 'header') return $calls[$i][1][1];
        if ($calls[$i][0] == 'section_open') return $calls[$i][1][0];
      }

      return 0;
    }
}
</code>

===== Revision History =====

  * 2008-08-13 --- Plugin URL updated.
  * 2005-09-30 --- Released.


===== To Do =====

===== Bugs =====



===== Discussion =====

>Great plugin. Very helpful for working around the quirks of the [[plugin:ifauth]] plugin. Thanks! ~SherriW

Ah, interesting plugin!

I was looking for something like this, but didn't know how to search for it.  I think that it would sense to make a notation on [[wiki:syntax#sectioning]], but since it's an optional plug-in, it probably clutters the documentation more than the average user would worry about.  The naming is of the plug-in is also a bit mystical, because I usually think of "outdenting" as a hanging indent (e.g. instead of the having the first line pushed to the right by a half-inch, it either means the first line is pushed to the left by a half-inch, or the first line is left in place and all subsequent links are pushed to the right by a half-inch).  A better description would probably be "unsectioning" or "unheading".  (I guess since I've entered those terms, now, this plug-in has to potential to be better found in searches!)  - David Ing, 2006/01/30

----
Could your plugin be modified to create section break without changing the level, indentation or anything else, just section break. I need this thing badly. Unfortunately I myself is a dummy in programming.  --- //[[az@libfl.ru|az]] 2007-03-24 23:20//