Documentation improvements

gillyb · Apr 11, 2017 · ccdff73 · ccdff73
1 parent 077cecd
commit ccdff73
Show file tree

Hide file tree

Showing 7 changed files with 35 additions and 26 deletions.
diff --git a/.todo.txt/done.txt b/.todo.txt/done.txt
@@ -30,3 +30,10 @@ x 2015-06-02 document .progressBar() .stop() and .resume() @doc
 x 2015-06-02 document .processExit() @doc
 x 2015-12-11 TextBuffer class suitable for text editor @code
 x 2015-12-28 ScreenBuffer generateOptimizedEscapeSequence() does not works well with style @code
+x 2017-04-11 document .inputField() option 'keyBindings' @doc
+x 2017-04-11 document .inputField() options 'minLength', 'default', 'style' and 'cancelable' @doc
+x 2017-04-11 document .markupOnly @doc
+x 2017-04-11 document .progressBar() option 'syncMode'
+x 2017-04-11 document fileInput @doc
+x 2017-04-11 document inputField autoComplete returning an array with a prefix key @doc
+x 2017-04-11 document all the ScreenBuffer feature @doc
diff --git a/.todo.txt/todo.txt b/.todo.txt/todo.txt
@@ -4,14 +4,5 @@ use the 'name' attribute of color, in colorScheme/ palette, something like accep
 (C) find why 24 bits colors test sucks so much in 16 colors terminal @bug
 try to find a way to disable terminal's word-wrap, if possible @r&d
 mrxvt support: draw-test does not work @bug
-(B) tests should be run with .getDetectedTerminal() AND default terminal, they all need to implement a CLI switch for that @code
 (E) terminfo support @code
-(C) document all the ScreenBuffer feature @doc
 (B) .inputField() has a bug with full-width chars @bug
-(B) ScreenBuffer char_size should be 2 bytes, punycode.ucs2.decode() is useless since bigger chars uses two cells @code
-(A) document inputField autoComplete returning an array with a prefix key @doc
-(A) document fileInput @doc
-(A) document .inputField() options 'minLength', 'default', 'style' and 'cancelable' @doc
-(A) document .inputField() option 'keyBindings' @doc
-(A) document .markupOnly @doc
-(A) document .progressBar() option 'syncMode'
diff --git a/.todo.txt/todo.txt.bak b/.todo.txt/todo.txt.bak
@@ -4,13 +4,6 @@ use the 'name' attribute of color, in colorScheme/ palette, something like accep
 (C) find why 24 bits colors test sucks so much in 16 colors terminal @bug
 try to find a way to disable terminal's word-wrap, if possible @r&d
 mrxvt support: draw-test does not work @bug
-(B) tests should be run with .getDetectedTerminal() AND default terminal, they all need to implement a CLI switch for that @code
 (E) terminfo support @code
-(C) document all the ScreenBuffer feature @doc
+x 2017-04-11 document all the ScreenBuffer feature @doc
 (B) .inputField() has a bug with full-width chars @bug
-(B) ScreenBuffer char_size should be 2 bytes, punycode.ucs2.decode() is useless since bigger chars uses two cells @code
-x 2015-12-28 ScreenBuffer generateOptimizedEscapeSequence() does not works well with style @code
-(A) document inputField autoComplete returning an array with a prefix key @doc
-(A) document fileInput @doc
-(A) document .inputField() options 'minLength', 'default', 'style' and 'cancelable' @doc
-(A) document .inputField() option 'keyBindings' @doc
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,4 +1,10 @@
 
+v1.2.4
+------
+
+Documentation improvements
+
+
 v1.2.1 - v1.2.3
 ---------------
 

diff --git a/doc/high-level.md b/doc/high-level.md
@@ -273,7 +273,9 @@ It produces:
 	  if multiple candidate are possible, it should return an array of string), if **the function accepts 2 arguments**
 	  (checked using *function*.length), then **the auto-completer will be asynchronous**!
 	  Also note that if it is an array or the result of the function is an array, and if that array has a
-	  special property `prefix` (a string), then this prefix will be prepended to the output of the auto complete menu.
+	  special property `prefix` (a string), then this prefix will be prepended to the output of the auto complete menu,
+	  and if it has the special property `postfix` (still a string), this will be appended to the output of the
+	  auto complete menu.
 	* autoCompleteMenu `boolean` or `Object` of options, used in conjunction with the 'autoComplete' options, if *truthy*
 	  any auto-complete attempt having many completion candidates will display a menu to let the user choose between each
 	  possibilities. If an object is given, it should contain options for the [.singleLineMenu()](#ref.singleLineMenu)
@@ -640,8 +642,17 @@ When the user press RETURN/ENTER, it displays the index, text and coordinates of
 	* barHeadChar `string` the char used for the bar, default to '>'
 	* maxRefreshTime `number` the maximum time between two refresh in ms, default to 500ms
 	* minRefreshTime `number` the minimum time between two refresh in ms, default to 100ms
-
-It creates a nice progress bar and return a controller object to interact with it.
+	* syncMode `boolean`
+		* when false (the default), the progressBar works asynchronously, every few milliseconds
+		  it is redrawn. Note that it will fail for CPU bound tasks, if the tasks do not let the event loop breathes
+		* when true, the *progressBar* works in synchronous mode: it only redraws itself synchronously in those cases:
+			* at startup when `progressBar()` is called
+			* each time `progressBar.startItem()` is called
+			* each time `progressBar.itemDone()` is called
+			* each time `progressBar.update()` is called
+			* each time `progressBar.resume()` is called
+
+It creates a nice progress bar and returns a controller object to interact with it.
 
 The controller provides those functions:
 

diff --git a/doc/low-level.md b/doc/low-level.md
@@ -95,12 +95,12 @@ See [the full style markup reference](https://github.com/cronvel/string-kit#ref.
 * .black(): ...
 * .red(): ...
 * .green(): ...
-* .yellow(): dark yellow, most of time brown or orange
+* .yellow(): dark yellow, most of time it is brown or orange
 * .blue(): ...
 * .magenta(): ...
 * .cyan(): ...
 * .white(): ...
-* .brightBlack(): ...
+* .brightBlack()/.gray(): dark gray
 * .brightRed(): ...
 * .brightGreen(): ...
 * .brightYellow(): true yellow
@@ -132,7 +132,7 @@ See [the full style markup reference](https://github.com/cronvel/string-kit#ref.
 * .bgCyan(): ...
 * .bgWhite(): ...
 * .bgDarkColor(): ...
-* .bgBrightBlack(): ...
+* .bgBrightBlack()/.bgGray(): dark gray
 * .bgBrightRed(): ...
 * .bgBrightGreen(): ...
 * .bgBrightYellow(): true yellow
@@ -234,8 +234,9 @@ See [the full style markup reference](https://github.com/cronvel/string-kit#ref.
 * .error(): it just set error to true so it will write to STDERR instead of STDOUT
 * .str(): do not output anything, instead return a string containing the sequences
 * .bell(): emit an audible bell
-* .noFormat(str): disable string formatting - useful when your string may contain `%` (e.g. user input) and you
-	don't want to escape them
+* .noFormat(str): disable all string formatting and markup, output *str* without interpreting it - useful when your
+  string may contain `%` and `^` (e.g. user input) and you don't want to escape them
+* .markupOnly(str): disable string formatting but still interpret `^` markup
 * .windowTitle(str): set the title of an xterm-compatible window to *str*
 * .setCursorColor(register): set the cursor color to one of the 256 *register*
 * .setCursorColorRgb(r,g,b): set the cursor color to a custom RGB value

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "terminal-kit",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "256 colors, keys and mouse, input field, progress bars, screen buffer (including 32-bit composition and image loading), text buffer, and many more... Whether you just need colors and styles, build a simple interactive command line tool or a complexe terminal app: this is the absolute terminal lib for Node.js!",
   "main": "lib/termkit.js",
   "directories": {