DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
plugin:cli

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
plugin:cli [2023-04-10 17:27] – compatible with jack jackrum (tested) schplurtzplugin:cli [2023-04-15 21:12] (current) – Aleksandr
Line 1: Line 1:
-====== CLI : a Command Line Interface formatter Plugin  ======+====== CLI: a Command Line Interface formatter Plugin  ======
  
 ---- plugin ---- ---- plugin ----
Line 18: Line 18:
 screenshot_img :  screenshot_img : 
 ---- ----
- 
  
 ===== Description ===== ===== Description =====
  
-This plugin brings a Command Line Interface formatter to Dokuwiki+This plugin brings a Command Line Interface formatter to DokuWiki
 allowing you to format the output of a transcript say for a user 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 manual or on-line tutorial. It is designed to work with the output
Line 42: Line 41:
 ===== Installation ===== ===== Installation =====
  
-Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.+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 ===== ===== Examples/Usage =====
Line 55: Line 54:
   </cli>   </cli>
  
-{{https://imagizer.imageshack.com/img924/3346/k5o8ZG.png}}+{{ https://imagizer.imageshack.com/img924/3346/k5o8ZG.png }}
  
 Next example shows that ''<cli>'' can nest, and shows the shortcut ''<cli type=dos>'' in action. Next example shows that ''<cli>'' can nest, and shows the shortcut ''<cli type=dos>'' in action.
Line 86: Line 85:
   </cli>   </cli>
  
-{{https://imagizer.imageshack.com/img922/9683/0hAkoB.png}}+{{ https://imagizer.imageshack.com/img922/9683/0hAkoB.png }}
  
 Custom prompts, when there are no satisfying defaults Custom prompts, when there are no satisfying defaults
Line 102: Line 101:
   </cli>   </cli>
  
-{{https://imagizer.imageshack.com/img924/3301/IAyO54.png}}+{{ https://imagizer.imageshack.com/img924/3301/IAyO54.png }}
  
 ===== Syntax ===== ===== Syntax =====
Line 113: Line 112:
  
   * //prompt// --- [optional] the prompt used by the CLI. See configuration below for the description of the syntax. If omitted, the default value is used.   * //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//.+  * //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.   * //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''. +  * //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]]. +  * //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. 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 single quotes, «\\» stands for «\» and «\'%%%%» stands for «%%'%%».
 +
 Within double 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 «>».+ 
 +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. There may be spaces around the equal sign.
-The following examples are all equivalent :+The following examples are all equivalent:
   <cli comment=\"\ >   <cli comment=\"\ >
   <cli comment =  "\" ">   <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.+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+Values are always set in this order: default, shortcut, individual settings. I.e. 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="%%===>%%". ''<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="%%===>%%".
  
Line 141: Line 143:
 The plugin has 9 configuration settings. The first 3 are the default prompts and comment marker to use. 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. Ie ''%%/^.*?> /%%'' is correct, but <del>''%%/> /%%''</del> is not. Note that ''"> "'' is correct as it is a string and not a regexp.+  * //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 <del>''%%/> /%%''</del> 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//.   * //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.   * //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.
Line 147: Line 149:
 If any of these is empty, then the cli plugin uses a harcoded internal value that corresponds to the defaults shown below. If any of these is empty, then the cli plugin uses a harcoded internal value that corresponds to the defaults shown below.
  
-Default values :+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.   * //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.   * //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.+  * //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 ''<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 :+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 ''<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   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). +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//<code>   * //namedprompt//<code>
Line 176: Line 178:
 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. 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 [[dw>plugin:odt|odt]] plugin.+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 ==== ==== odt support ====
  
-When exporting a page to odt with the [[dw>plugin:odt|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//.+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 //<code>// or //<file>// is used : ''#f7f9fa''. +  * //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'' +  * //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''+  * //odtbordercolor// is the border colour. by default, the same as //<code>// or //<file>//: ''#8cacbb''
  
 ==== style ==== ==== 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 [[doku>devel:css#user_styles|user styles]]. This example should work with most dokuwiki [[dw>template|templates]].+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]].
  
 <code css userstyle.css> <code css userstyle.css>
Line 236: Line 238:
   </cli>   </cli>
  
-{{https://imagizer.imageshack.com/img921/2705/8iB6AN.png}}+{{ https://imagizer.imageshack.com/img921/2705/8iB6AN.png }}
  
   <cli green uppercase>   <cli green uppercase>
Line 246: Line 248:
   </cli>   </cli>
  
-{{https://imagizer.imageshack.com/img922/3950/HWLFjg.png}}+{{ https://imagizer.imageshack.com/img922/3950/HWLFjg.png }}
  
   <cli type=dos retro-ochre reverse>   <cli type=dos retro-ochre reverse>
Line 262: Line 264:
   </cli>   </cli>
  
-{{https://imagizer.imageshack.com/img924/6294/Jqebtx.png}}+{{ https://imagizer.imageshack.com/img924/6294/Jqebtx.png }}
  
------------------+----
  
 A few technical details. 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>'' are rendered as html ''<pre>'' tags with ''cli'' class. Classe from the ''type'' attribute is added as well as optional classes.
  
Line 281: Line 284:
 </code> </code>
  
-A full example :+A full example:
  
 <code xml> <code xml>
Line 322: Line 325:
 === ToDo/Wish List === === ToDo/Wish List ===
  
-Please, create an issue on [[https://github.com/schplurtz/dokuwiki-plugin-cli/issues|github]]+Please, create an issue on [[https://github.com/schplurtz/dokuwiki-plugin-cli/issues|GitHub]].
  
 ===== FAQ ===== ===== FAQ =====
Line 329: Line 332:
 ===== Discussion ===== ===== Discussion =====
  
-Please, discuss on the [[https://forum.dokuwiki.org/|forum]]+Please, discuss on the [[https://forum.dokuwiki.org/|forum]].
  
  
- +----
------------------------+
  
  
 ===== Acknowledgements ===== ===== Acknowledgements =====
  
-This plugin was originally written in 2007 by +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]].
-[[https://github.com/cpjobling|Chris P. Jobling]].  He was inspired +
-by a similar feature found in [[http://moinmoin.wikiwikiweb.de/|MoinMoin +
-Wiki]] and [[http://www.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 +
-[[http://dokuwiki.org/plugin:tutorial|Plugin Tutorial]] and +
-Christopher Smith's implementation and documentation of the +
-[[http://dokuwiki.org/plugin:boxes|boxes plugin]].+
  
 Several improvements suggested by Stephane Chazelas and Andy Webber. Several improvements suggested by Stephane Chazelas and Andy Webber.
  
-More than 12 years after its creation, this plugin was +More than 12 years after its creation, this plugin was modernized by Schplurtz le Déboulonné who added a few features.
-modernized by Schplurtz le Déboulonné who added a few features.+
  
  
plugin/cli.txt · Last modified: 2023-04-15 21:12 by Aleksandr
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Global DokuWiki Links