console-docbook-xml-viewer 1 user commands nosh
console-docbook-xml-viewer TUI viewer for UTF-8 DocBook XML references
`console-docbook-xml-viewer` --cursor-keypad-application-mode --calculator-keypad-application-mode --no-alternate-screen-buffer --inversescreen boolean --tui-level level filename(s)

## Description

`console-docbook-xml-viewer` is a simple TUI viewer for UTF-8 encoded DocBook XML reference manuals.

The manual data are read from the command's standard input, or the list of files denoted by filename(s), and parsed at startup; before its initializes its display.

### Documents

`console-docbook-xml-viewer` ignores XML Prologues and Document Type Definitions. Documents are simply assumed to be encoded in UTF-8 and marked up as references.

Most documents nowadays are encoded as UTF-8. Simply pass any that are not through iconv 1 or a similar tool.

Documents that are DocBook entities other than references, such as book chapters and appendixes, may not render ideally. The primary target is a reference manual document with `<refentry>`s.

### User interface

`console-docbook-xml-viewer` opens its controlling terminal via `/dev/tty` and uses that for its user interface, both input and output.

If its standard input is also its controlling terminal, odd behaviour may result, determined by how the operating system kernel decides to route input. This is not a sensible usage of the program; so simply do not do this.

Although its behaviour is controlled by the `TERM` 7 environment variable, it does not use terminfo 3 or termcap 3. It instead uses TerminalCapabilities 3. The terminal type determines a few terminal capabilities (such as whether the terminal can actually handle DEC private mode control sequences at all, and its degree of ISO 8613-6/ITU T.416 support), but most processing adheres to the ECMA-48 and ISO 8613-6 de jure standard control sequences and the DEC VT, DTTerm, and AIXTerm de facto standard ones.

The user interface responds to actual arrow keys, HJKL navigation in the style of vi 1, and WASD navigation. (The command only knows about characters and escape/control sequences coming from the terminal. Thus the latter two are not particularly ergonomic on several countries' standard keyboard layouts.)

The cursor is initially positioned on the first line, so the screen will not begin to scroll until the cursor is moved to the bottom.
SPC and LF characters as input do not do anything; this not being a pagination tool.

Various common control characters with conventional special meanings may be used to quit, although the simplest way of quitting is simply `q`.

The --cursor-keypad-application-mode and --calculator-keypad-application-mode command-line options instruct `console-docbook-xml-viewer` to switch, respectively, the cursor keypad and the calculator keypad of the realizing terminal into their "application" modes. Otherwise it switches them into their "normal" modes. "application" mode is generally not useful to `console-docbook-xml-viewer`, since it makes cursor and calculator keys indistinguishable from accelerator keys. The --no-alternate-screen-buffer command-line option instructs `console-docbook-xml-viewer` to not switch to the alternative screen buffer. This has two uses. First, it allows one to retain visibility of displayed information after the program has exited (although setterm 1 provides access to the alternative screen buffer). Second, it works around problems with some (yet more!) broken terminal emulators that attempt to be and fail at being like XTerm, which forcibly change cursor and editing keys into application mode when the alternative screen buffer is active. The --inversescreen command-line option instructs `console-docbook-xml-viewer` to switch the DECSCNM ("light"/"dark" screen mode) private mode on or off. The --tui-level command-line option constrains the use of MouseText or Unicode block graphics and line drawing characters in TUI widgets; currently none.

### Limitations

`console-docbook-xml-viewer` by design will not render graphical elements such as images. Moreover, its internal document model is a simple one, that does not handle tables well. To view documents with images and tables, use a GUI viewer. Many GUI HTML viewers can be persuaded to view DocBook XML with the simple addition of a stylesheet. (One such stylesheet can be found in the nosh Guide.)

Real XML processors are less forgiving than `console-docbook-xml-viewer`, which allows some constructs that are not actually well-formed XML. Do not rely upon this; future versions are free to be more strict.

The internal document model will not cope well with some valid, but unusual, ways of writing reference manuals. Generally <title> elements are expected to come first in sections, <refname> elements to come before <refpurpose> elements, and <refentrytitle> elements to come before <manvolnum> elements. Fortuately, these are the logical ways for human authors to write.

## Author

Jonathan de Boyne Pollard