DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:cli

CLI : a Command Line Interface formatter Plugin

Compatible with DokuWiki

  • 2020-07-29 "Hogfather" yes
  • 2018-04-22 "Greebo" yes
  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" yes

plugin Format command line transcripts

Last updated on
2020-08-18
Provides
Syntax
Repository
Source

Similar to konsole, xterm, xterm2

Tagged with cli, code, highlighting, syntax

Description

This plugin brings a Command Line Interface formatter to Dokuwiki allowing you to format the output of a transcript say for a user manual or on-line tutorial. It is designed to work with the output of a standard Unix Bash Shell, but is suitable to document other kinds of CLI interaction, e.g. Windows Command Window, Python and Ruby, Matlab, etc.

The assumptions made are

  1. all user commands start with a prompt
  2. the CLI prompt will end in a recognizable character (typically '$' or '>')
  3. user commands will follow the CLI prompt on the same line
  4. user commands may contain a comment introduced by an easily recognizable character (usually '#')
  5. lines that do not start with a prompt are outputs from the CLI.

A key design feature is that it should be possible to display a CLI transcript (e.g. output from a history file or copy of text from a console window) for display with the mimumum of additional markup.

Very complicated prompts can be recognized with regexp; see Configuration and Settings for the details. It is possible to adjust the style of the display using a style sheet. For details refer to style.

Installation

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Examples/Usage

A simple Bash Shell interaction:

<cli>
user@host:~/somedir $ ls # List current directory
conf      lang         README        screen.gif  ui
info.txt  manager.dat  renderer.php  syntax.php
user@host:~/somedir $ 
</cli>

Next example shows that <cli> can nest, and shows the shortcut <cli type=dos> in action.

<cli>
user@host:~/somedir $ dosemu
<cli type=dos>
(C) Copyright 1995-2006 Pasquale J. Villani and The FreeDOS Project.
D: = LINUX\FS/HOME/USER attrib = READ/WRITE
E: = LINUX\FS/MEDIA/CDROM CDROM:1 attrib = READ ONLY
"Welcome to dosemu 1.4.0.8!"
C:\>dir
 Volume in drive C is mu/drives/c
 Directory of C:\

TMP                  <DIR>  12-28-17  6:29a
CONFIG   SYS           346  06-22-15  1:17a
AUTOEXEC BAT           556  06-22-15  1:17a
         2 file(s)            902 bytes
         1 dir(s)   2,147,450,880 bytes free
C:\>echo pouet
pouet
C:\>rem This is a remark and does nothing
C:\>echo But this rem is not a remark.
But this rem is not a remark.
C:\>exit
</cli>
user@host:~/somedir $ echo Back to normal again
Back to normal again
user@host:~/somedir $
</cli>

Custom prompts, when there are no satisfying defaults

<cli prompt="SQL> " comment="--" continue="/^\s*[0-9]{1,4}  /">
SQL> select
   2  * --comment
   3  from
   4  dual;

D
-
X

SQL>
</cli>

Syntax

The full syntax:

<cli prompt='some prompt' continue='continue prompt' comment='comment' type=shortcut class class...>
session transcript
</cli>
  • prompt — [optional] the prompt used by the CLI. See configuration below for the description of the syntax. If omitted, the default value is used.
  • continue — [optional]. The continue prompt used by the CLI. See configuration below for the description of the syntax. If ommitted, the default value is used. A continue prompt is an alternate prompt that can only happen immediately after a line containing a prompt, of any kind.
    NB
    continue can be abbreviated cont.
  • comment — [optional] the comment used by the CLI. See configuration below for the description of the syntax. If omitted, the default value is used.
  • shortcut — [optional] This is the name of a shortcut, ie a predefined set of prompt, continue and comment. It is not an error to use an undefined shortcut. It simply has no effect. Shortcuts are also useful to customize the visual aspect of the session since the shortcut name is added as classname in the html block.. See Style below.
    NB
    one may write type=shortcut, or t=shortcut, language=shortcut, lang=shortcut, lng=shortcut, l=shortcut.
  • class — [optional] Class to add to the html block. This allows to create all sorts of custom style.

Each of the values may be enclosed in single (') or double (") quote if they have spaces or tabs in them. Within single quotes, «\\» stands for «\» and «\'» stands for «'». Within double quotes, «\\» stands for «\» and «\"» stands for «"». In unquoted strings, the following characters must be \-escaped to be part of the string : «“», «'», « » (space), «=», «\» and «>».

There may be spaces around the equal sign. The following examples are all equivalent :

<cli comment=\"\ >
<cli comment =  "\" ">
<cli 'comment'='" '>

The opening <cli … > must all appear on one line. The transcript contents can appear over as many lines as are needed.

Values are always set in this order : default, shortcut, individual settings. Ie if you write something like <cli continue=”===>“ t=irb>, the continue value is first set from defaults, then overridden by the shortcut and finally overridden by the value of the continue attribute. So in the end, in this example, continue=”===>“.

Default values match most unix shells use.

Configuration and Settings

The plugin has 9 configuration settings. The first 3 are the default prompts and comment marker to use.

  • prompt is a either a regexp1) that describe the prompt your CLI uses, or a string that should be equal the last char or chars of the prompt. When a regexp is used, it must match from the start of line to the last char considered part of the prompt. Ie /^.*?> / is correct, but /> / is not. Note that ”> “ is correct as it is a string and not a regexp.
  • continue is a description of the continue prompt. It uses the same syntax as prompt.
  • comment is a description of the comment marker. Also a string or regexp. It is matched only to the part of each transcript lines after the prompt. For this regexp, the start of line is the first non-prompt char of a command line.

If any of these is empty, then the cli plugin uses a harcoded internal value that corresponds to the defaults shown below.

Default values :

  • prompt /^.{0,30}?[$%>#](?:$|\s)/
    That is the shortest string of at most 30 chars that ends in $, %, > or # followed by a space or end of line.
  • continue /^.{0,30}?>(?:$|\s)/
    That is the shortest string of at most 30 char that ends in > followed by a space or end of line.
  • comment /(?:^#)|\s#/
    That is either a sharp sign at start of line (right after the prompt) or a space followed by a sharp sign.

The next three settings (namedprompt, namedcontinue, namedcomment) are used to create named shortcuts. Although default values will work for most of the unix CLI, there are some situations when those defaults won't work. For example, the irb ruby shell needs special values for prompt, continue and comment. Instead of typing each time <cli prompt='/^(>|irb.*?:\d+:\d+|(?:ruby-?)?\d.*?:\d+\s)>\s/' continue='@^(\?>|irb.*?:\d+:\d+[]\'”/`*>]|(?:ruby-?)?\d.*?:\d+[]\'“/`?]>)\s@' comment='/#(?!{)/' >, which is tedious and error-prone, you may use the previously created irb shortcut : <cli t=irb>. Shortcuts define some replacements for prompt, continue and comment. The syntax to define shortcut is this :

name:regexp-or-string

It is not necessary that values are given for the three of them. The defaults below define shortcuts for interactive ruby (irb), cisco-like CLI (nospace), MS dos and powershell (dos), and python (python).

  • namedprompt
    irb:/(?x) ^ ( > | irb.*?:\d+:\d+ | (?: ruby-?)? \d.*?:\d+\s )>\s /
    nospace:/^.{0,30}?[$%>#]/
    dos:/^[A-Z]:.{0,28}?>/
  • namedcontinue
    irb:@(?x) ^ ( \?> | irb.*?:\d+:\d+[]'"/`*>] | (?: ruby-?)? \d.*?:\d+[]'"/`?]> )\s @
    R:/^\+ /
    python:...
    nospace:undef continue
  • namedcomment
    irb:/#(?!{)/
    dos:/^\s*rem(\s+|$)/

As you can see, for python, you only have to define a continue replacement, as the standard prompt definition will also catch the python prompt. irb needs to replace all the three definitions. The continue prompt undef continue is not special at all; this definition replaces the standard definition and will (most probably) never happen in real life. So it actually disables the continue prompt.

The last set of configuration options, odtbackground, odtborderwidth and odtbordercolor are used when exporting to odt with the help of the odt plugin.

odt support

When exporting a page to odt with the odt plugin, font colours are taken from the CSS default style. Computer output is blue, prompt is green, user input red and comments orange. You may change the default colours for both html and odt by creating a custom style, The background, and background border are controlled by the 3 configuration options odtbackground, odtborderwidth and odtbordercolor.

  • odtbackground is the Background colour. By default, the same colour as the one used for <code> or <file> is used : #f7f9fa.
  • odtborderwidth is the border width. by default, the same as <code> or <file> : 0.06pt
  • odtbordercolor is the border colour. by default, the same as <code> or <file> : #8cacbb

style

You may customize the colours of the text and also the border, background, padding, margin, font etc… well, pretty much anything customizable with CSS. Where to create your CSS files is documented in user styles. This example should work with most dokuwiki templates.

userstyle.css
#dokuwiki__content pre.cli {
  /* This changes the default style */
  background-color: #000;
  span.cli_prompt  { color: red }
  span.cli_command { color: white }
  span.cli_comment { color: grey }
  span.cli_output  { color: yellow }
  /* retro green and retro green with prompt in reverse video */ 
  &.retro-green, div.retro-green {
    background-color: #1e2e15;
    span.cli_prompt  { color: #0bc81b }
    span.cli_command { color: #8fe35f }
    span.cli_comment { color: #69a845 }
    span.cli_output  { color: #93eb60 }
    &.reverse {
      span.cli_prompt  { color: #1e2e15; background-color: #93eb60; font-weight: bold }
    }
  }
  /* retro ochre and retro ochre with prompt in reverse video */ 
  &.retro-ochre, div.retro-ochre {
    background-color: #2b2514;
    span.cli_prompt  { color: #ff8a11 }
    span.cli_command { color: #ffbf0e }
    span.cli_comment { color: #a87f0d }
    span.cli_output  { color: #de7407 }
    &.reverse {
      span.cli_prompt  { color: #2b2514; background-color: #de7407; font-weight: bold }
    }
  }
  /* Just for fun, but should be useless */
  &.uppercase, div.uppercase {
    text-transform: uppercase;
  }
}

Here are some examples

<cli>
me@mycomputer (0) $ ls # list files
README			i			prompt-plugin.txt
basic-usage.png		lang			style.css
conf			plugin.info.txt		syntax.php
dos-example.png		prompt-examples.txt
</cli>

<cli green uppercase>
me@mycomputer (0) $ ls -adtr * # list files with weid args
README			i			prompt-plugin.txt
basic-usage.png		lang			style.css
conf			plugin.info.txt		syntax.php
dos-example.png		prompt-examples.txt
</cli>

<cli type=dos retro-ochre reverse>
C:\>dir
 Volume in drive C is mu/drives/c
 Directory of C:\
TMP                  <DIR>  12-28-17  6:29a
CONFIG   SYS           346  06-22-15  1:17a
AUTOEXEC BAT           556  06-22-15  1:17a
         2 file(s)            902 bytes
         1 dir(s)   2,147,450,880 bytes free
C:\>echo pouet
pouet
C:\>rem This is a remark and does nothing
</cli>


A few technical details. <cli> are rendered as html <pre> tags with cli class. Classe from the type attribute is added as well as optional classes.

<cli type=dos retro-ochre reverse>

is rendered as

<pre class="cli dos  retro-ochre reverse">
<!--        ^   ^     additional classes
            |   |
            |   +---- type=dos. added as a class
            |
            +-------- class cli is always present
-->

A full example :

<cli retro-ochre>
me@mycomputer (0) $ dosemu # let's go back in the 80s
<cli type=dos>
C:>rem This is a remark and does nothing
C:>echo pouet
pouet
C:>exit
</cli>
me@mycomputer (0) $ 
</cli>

Will produce this html code

<pre class="cli   retro-ochre">
<span class="cli_prompt">me@mycomputer (0) $ </span><span class="cli_command">dosemu</span><span class="cli_comment"> # let's go back in the 80s</span>
<div class="dos ">
<span class="cli_prompt">C:&gt;</span><span class="cli_comment">rem This is a remark and does nothing</span>
<span class="cli_prompt">C:&gt;</span><span class="cli_command">echo pouet</span>
<span class="cli_output">pouet</span>
<span class="cli_prompt">C:&gt;</span><span class="cli_command">exit</span>
</div>
<span class="cli_prompt">me@mycomputer (0) $ </span><span class="cli_command">exit</span>
</pre>

Development

Change Log

ToDo/Wish List

Please, create an issue on github

FAQ

Discussion

Please, discuss on the forum


Acknowledgements

This plugin was originally written in 2007 by Chris P. Jobling. He was inspired by a similar feature found in MoinMoin Wiki and TiddlyWiki. The styles were based on those developed for the UNIX Tutorial for Beginners by Michael Stonebank. The plugin and its documentation were based on lessons Chris learned from the Plugin Tutorial and Christopher Smith's implementation and documentation of the boxes plugin.

Several improvements suggested by Stephane Chazelas and Andy Webber.

More than 12 years after its creation, this plugin was modernized by Schplurtz le Déboulonné who added a few features.

1)
enclosed in «/», «|», «=», «,», «;», «%», «@», «=», or «#»
plugin/cli.txt · Last modified: 2020-11-13 12:40 by Michaelsy