xterm Plugin

This plugin is intended to allow users to easily document the output of x-terminals by cutting and pasting directly to the the wiki edit window, without adding line feeds.

DokuWiki formatting options (bold, italic, etc…) can be applied to the text.

<xterm>
<linux:/home/zabbix$ **ls -l | grep**
drwxr-xr-x  2 zabbix zabbix   4096 Mar 23  2004 autom4te.cache
drwxr-xr-x  2 zabbix zabbix   4096 Oct  4  2004 bin
drwxr-xr-x  5 zabbix zabbix   4096 Mar 23  2004 create
drwxr-xr-x  2 zabbix zabbix   4096 Mar 23  2004 doc
</xterm>

To show the xterm text a CSS class needs to be defined. Add the following CSS to a new file /lib/plugins/xterm/style.css which will be automatically included when the plugin is loaded (recommended method), or add it to your existing /lib/tpl/default/design.css:

style.css

.xterm {
    font-family:MiscFixed;
    white-space:pre;
}

Put the following PHP file in /lib/plugins/xterm/syntax.php

syntax.php

<?php
/**
 * xterm Plugin: for documenting x-terminal output using Preformatted text
 * (avoid adding line feeds)
 * Syntax:     <xterm> text </xterm>
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Tom Trenker <tom_trenker@yahoo.com>  
 */
 
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_xterm extends DokuWiki_Syntax_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
          'author' => 'Tom Trenker',
          'email'  => 'tom_trenker@yahoo.com',
          'date'   => '2006-08-26',
          'name'   => 'xterm Plugin',
          'desc'   => 'for displaying xterm output using Preformatted text',
          'url'    => 'http://www.dokuwiki.org/plugin:xterm',
        );
    }
 
    /**
     * What kind of syntax are we?
     */
    function getType(){
        return 'formatting';
    }
 
    /**
     * What kind of syntax do we allow (optional)
     */
    function getAllowedTypes() {
        return array('formatting', 'disabled');
    }
 
    /**
     * What about paragraphs? (optional)
     */
   function getPType(){
       return 'normal';
   }
 
    /**
     * Where to sort in?
     */
    function getSort(){
        return 195;
    }
 
 
    /**
     * Connect pattern to lexer
     */
    function connectTo($mode) {
        $this->Lexer->addEntryPattern('<xterm>(?=.*</xterm>)',$mode,'plugin_xterm');
/*      $this->Lexer->addEntryPattern('(?i)<xterm(?: .+?)?>(?=.+</xterm>)',$mode,'plugin_xterm'); */
    }
 
    function postConnect() {
        $this->Lexer->addExitPattern('</xterm>', 'plugin_xterm'); 
/*      $this->Lexer->addExitPattern('(?i)</xterm>','plugin_xterm'); */        
    }
 
 
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
        switch ($state) {
          case DOKU_LEXER_ENTER : 
            break;
          case DOKU_LEXER_MATCHED :
            break;
          case DOKU_LEXER_UNMATCHED :
            break;
          case DOKU_LEXER_EXIT :
            break;
          case DOKU_LEXER_SPECIAL :
            break;
        }
        return array($match, $state);
    }
 
    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        if($mode == 'xhtml'){
            if ($data[1] == DOKU_LEXER_ENTER){
                $renderer->doc .= '<pre class="xterm">';       #     <pre><font size=+0>';
            } else if ($data[1] == DOKU_LEXER_UNMATCHED){
                $renderer->doc .= $renderer->_xmlEntities($data[0]);
            } else if ($data[1] == DOKU_LEXER_EXIT){
                $renderer->doc .= '</pre>';   #       '</font></pre>';
            }
            return true;
        }
        return false;
    }   
}
 
//Setup VIM: ex: et ts=4 enc=utf-8 :
 
?>

• This is my first attempt at a DokuWiki plugin, and although it works for fine for my purposes, I'm sure it could be written more cleanly. Please feel free to comment or point out my errors. Tom Trenker

• Would it be better to allow any formatting within the xterm by instead of matching the whole lot in DOKU_LEXER_UNMATCHED to use the rest of the state cases as normal and have getAllowedTypes return array('formatting') ? I'd like to have italics too for example. – Mike Battersby

• I tried your suggestion. It seems to work well. See the above code. Tom Trenker

• I'd strongly suggest to generate valid XHTML code. Not only is the FONT tag deprecated for ages (and not allowed at all in XHTML, see XHTML1 DTD), but also all tag attributes have to be enclosed in quotes (either single or double quotes). Matthias Watermann

I think replacing the <pre><font size=+0> with <pre class=“code”>, and dropping the </font> will bring the code into XHTML compliance. Ronald Bruintjes

• there seems to be a bug in that formatting markup tries to span <xterm> blocks. E.g., if you have

  <xterm>this has // two slashes</xterm>
  
  some text here
  
  <xterm>another two // slashes in later block</xterm>

  then the whole lot will be merged into one xterm block. :( – Mike Battersby

• You're right, this is a serious bug. I tried a few changes with no success. I'm hoping that I might be able to fix the problem with a different addEntryPattern. Any suggestions would be appreciated. Tom Trenker

• I think this is a wiki bug in general rather than with xterm. For example, if you put // into one list item and another // into a later list item, the two will be merged. It might be to do with the URL detection code. Perhaps you can lodge this as a wiki bug? – Mike Battersby

No its not (really) a bug and its not related to URL detection. DokuWiki doesn't verify that your markup makes sense. Markup must be properly nested to work correctly in all circumstances. So the correct markup is

<xterm>this has // two slashes//</xterm>//

some text here

//<xterm>//another two // slashes in later block</xterm>

Now nesting is correctly preserved. In technical terms, when you enter a new formatting mode (e.g. //) the exit pattern of the earlier mode (e.g. </xterm>) is no longer recognised. The exit pattern won't be a recognizable pattern until either that mode is entered again or we exit the new mode. — Christopher Smith 2006-01-05 12:09

• How i can change the background color of box ? Alessandro Celli 2006-06-21 15:20
• You can modify style.css to achieve a number of effects. The following is copied from the file tag:

/* code blocks by xterm tag */
div.dokuwiki pre.xterm {
  font-family:MiscFixed;
  white-space:pre;
  padding: 0.5em;
  border: 1px dashed __medium__;
  color: Black;
  background-color: __medium__;
  overflow: auto;
}

• xterm does not support the embedded HTML? i have try to use this: <html><font color=“blue” size=“+1”>CHOOSE</font></html> Alessandro Celli 2006-06-22 12:08
• I updated the xterm plugin to work with DokuWiki-2006-03-09.tgz, and I also implemented the use of CSS which will hopefully ensure XHTML compliance. Tom Trenker 2006-08-27
• 20060913: I made a minor modification to syntax.php to disable typography substitution by removing 'substition' from the getAllowedTypes() function call. Tom Trenker

Hi thank you very much for this plugin. Here is a possible design for a real terminal look:

/lib/tpl/YOUR_TEMPLATE/layout.css

/* code blocks by xterm tag */
div.dokuwiki pre.xterm {
  font-family:"Lucida Console",Monospace,"DejaVu Sans Mono","Courier New",MiscFixed;
  font-size: 12px;
  white-space:pre;
  padding: 0.5em;
  border: 2px solid #000000;
  color: #FFFFFF;
  background-color:#3F3F3F;
  overflow: auto;
}

/lib/plugin/xterm/style.css

.xterm {
  font-family:"Lucida Console",Monospace,"DejaVu Sans Mono","Courier New",MiscFixed;
  font-size: 12px;
  white-space:pre;
  padding: 0.5em;
  border: 2px solid #000000;
  color: #FFFFFF;
  background-color:#3F3F3F;
  overflow: auto;
}

Best regards,
Gürkan (have a look at our playground - there you'll see this design in action )

To get compatibility with 2020-07-29 “Hogfather” you need to change only the declarations of the functions handle and render → My wiki runs at least error free

--- lib/plugins/xterm/syntax.php.save   2020-08-21 16:12:48.530697306 +0200
+++ lib/plugins/xterm/syntax.php        2020-11-23 14:49:54.937881868 +0100
@@ -78,7 +78,8 @@
     /**
      * Handle the match
      */
-    function handle($match, $state, $pos, &$handler){
+    /* function handle($match, $state, $pos, &$handler){ */
+    function handle($match, $state, $pos, Doku_Handler $handler){
         switch ($state) {
           case DOKU_LEXER_ENTER :
             break;
@@ -97,7 +98,8 @@
     /**
      * Create output
      */
-    function render($mode, &$renderer, $data) {
+    /* function render($mode, &$renderer, $data) { */
+    function render($mode, Doku_Renderer $renderer, $data) {
         if($mode == 'xhtml'){
             if ($data[1] == DOKU_LEXER_ENTER){
                 $renderer->doc .= '<pre class="xterm">';       #     <pre><font size=+0>';

— kirbach 2020-11-23 15:05