thebespokepixel/term-ng

View on GitHub
src/docs/documentation.yml

Summary

Maintainability
Test Coverage
toc:
  - name: "Usage"
    example: "src/docs/example.md"

  - name: "CLI"
    description: |
      ```shell
        > npm install --global term-ng
        > term-ng --help

        term-ng v0.6.3

        Allow user configured enhanced terminal capabilities to be queried.

        The command will exit with status 0 if all the provided queries (except
        user-agent) are true, otherwise exits with status 1.

        If user-agent is used, the command will return the string on stdout and exit
        status 0.

        Usage:
        termng [command]

        Commands:
        has-color      Is basic color supported?
        has-256        Is 256 color supported?
        has-16m        Is 24 bit color supported?
        has-images     Are images supported? (set $TERM_IMAGES=enabled)
        has-audio      Is audio supported? (set $TERM_AUDIO=enabled)
        has-box-font   Is audio supported? (set $TERM_FONT=box)
        has-full-font  Is audio supported? (set $TERM_FONT=full)
        is-enhanced    Is the current terminal using an enhanced termcap?
                       (set $TERM_ENHANCED=enabled)
        user-agent     Print the current terminal software

        Options:
        -h, --help     Display this help.
        -v, --version  Return the current version on stdout. -vv Return name & version.
        --color        Force color depth --color=256|16m. Disable with --no-color

        © 2016 The Bespoke Pixel. Released under the MIT License.
      ```
  - name: "Enhancing termcap"
    description: |
      In some of my 'private' admin/control systems, I use a customised terminfo
      database that wraps some of the (very useful) enhanced OSC abilities of
      more recent iTerm builds into new commands available via `tput` (which I
      further wrap in fish functions).

      The `terminfo` directory above contains `iTerm.ti`. Using `/usr/bin/tic`
      and ncurses' terminfo database (available from
      <a href="http://invisible-island.net/ncurses/ncurses.html#downloads">invisible-island.net</a>),
      I build a new terminal type `xterm-256color+iterm3`, and change the
      Terminal type preference in iTerm to the same, setting the $TERM
      environment variable.

      The new terminfo entries are built thusly...

      ```shell
      cd term-ng/terminfo
      curl http://invisible-island.net/datafiles/current/terminfo.src.gz
      gunzip terminfo.src.gz
      tic -xrs -e xterm-256color terminfo.src
      tic -xsv3 iTerm.ti
      ```

      This create a new, updated xterm-256color and then extends it for iTerm.
      This is non-destructive as it creates new entries at ` ~/.terminfo/`.
      Simply delete this directory to return the terminfo databases back to the
      original OS provided state.

      A word of caution... while this has worked very well for me, I have found
      that some things complain about an unrecognized term type - Homebrew is
      notable here. A simple workaround is to have a standard `xterm-256color`
      session profile defined to use when brewing.
  - name: "API"
    description: |
      Returned object describing terminal features.