====== CLI: a Command Line Interface formatter Plugin ====== ---- plugin ---- description: Format command line transcripts author : Schplurtz le Déboulonné email : Schplurtz-AT-Laposte•net type : syntax lastupdate : 2020-08-18 compatible : elenor of tsort, detritus, frusterick manners, greebo, hogfather, igor, jack jackrum depends : conflicts : similar : konsole tags : code, cli, syntax, highlighting downloadurl: https://github.com/schplurtz/dokuwiki-plugin-cli/zipball/master bugtracker : https://github.com/schplurtz/dokuwiki-plugin-cli/issues sourcerepo : https://github.com/schplurtz/dokuwiki-plugin-cli donationurl: screenshot_img : ---- ===== 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 - all user commands start with a prompt - the CLI prompt will end in a recognizable character (typically '$' or '>') - user commands will follow the CLI prompt on the same line - user commands may contain a comment introduced by an easily recognizable character (usually '#') - 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 [[extension|Extension Manager Plugin]] 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: user@host:~/somedir $ ls # List current directory conf lang README screen.gif ui info.txt manager.dat renderer.php syntax.php user@host:~/somedir $ {{ https://imagizer.imageshack.com/img924/3346/k5o8ZG.png }} Next example shows that '''' can nest, and shows the shortcut '''' in action. user@host:~/somedir $ dosemu (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 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 user@host:~/somedir $ echo Back to normal again Back to normal again user@host:~/somedir $ {{ https://imagizer.imageshack.com/img922/9683/0hAkoB.png }} Custom prompts, when there are no satisfying defaults SQL> select 2 * --comment 3 from 4 dual; D - X SQL> {{ https://imagizer.imageshack.com/img924/3301/IAyO54.png }} ===== Syntax ===== The full syntax: session transcript * //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, i.e. 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: The opening ''****'' 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. I.e. if you write something like '''', 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 regexp((enclosed in <<''/''>>, <<''|''>>, <<''=''>>, <<'',''>>, <<'';''>>, <<''%''>>, <<''@''>>, <<''=''>>, or <<''#''>>)) 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. I.e. ''%%/^.*?> /%%'' 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 [[http://www.ruby-lang.org/|ruby]] shell needs special values for //prompt//, //continue// and //comment//. Instead of typing each time '']|(?:ruby-?)?\d.*?:\d+[]\'"/`?]>)\s@' comment='/#(?!{)/' >'', which is tedious and error-prone, you may use the previously created irb shortcut: ''''. 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 [[#style|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 //// or //// is used: ''#f7f9fa''. * //odtborderwidth// is the border width. by default, the same as //// or ////: ''0.06pt'' * //odtbordercolor// is the border colour. by default, the same as //// or ////: ''#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 [[devel:css#user_styles|user styles]]. This example should work with most dokuwiki [[:template|templates]]. #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 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 {{ https://imagizer.imageshack.com/img921/2705/8iB6AN.png }} 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 {{ https://imagizer.imageshack.com/img922/3950/HWLFjg.png }} C:\>dir Volume in drive C is mu/drives/c Directory of C:\ TMP 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 {{ https://imagizer.imageshack.com/img924/6294/Jqebtx.png }} ---- A few technical details. '''' are rendered as html ''
'' tags with ''cli'' class. Classe from the ''type'' attribute is added as well as optional classes.

  
is rendered as





A full example:



me@mycomputer (0) $ dosemu # let's go back in the 80s

C:>rem This is a remark and does nothing
C:>echo pouet
pouet
C:>exit

me@mycomputer (0) $ 



Will produce this html code



me@mycomputer (0) $ dosemu # let's go back in the 80s


C:>rem This is a remark and does nothing
C:>echo pouet
pouet
C:>exit


me@mycomputer (0) $ exit





===== Development =====


=== Change Log ===

{{rss>https://github.com/schplurtz/dokuwiki-plugin-cli/commits/master.atom date}}


=== ToDo/Wish List ===

Please, create an issue on [[https://github.com/schplurtz/dokuwiki-plugin-cli/issues|GitHub]].

===== FAQ =====


===== Discussion =====

Please, discuss on the [[https://forum.dokuwiki.org/|forum]].


----


===== Acknowledgements =====

This plugin was originally written in 2007 by [[https://github.com/cpjobling|Chris P. Jobling]]. He was inspired by a similar feature found in [[http://moinmo.in/|MoinMoin Wiki]] and [[http://tiddlywiki.com/|TiddlyWiki]]. The styles were based on those developed for the [[http://www.ee.surrey.ac.uk/Teaching/Unix/|UNIX Tutorial for Beginners]] by Michael Stonebank. The plugin and its documentation were based on lessons Chris learned from the [[tutorial|Plugin Tutorial]] and Christopher Smith's implementation and documentation of the [[box|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.