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) 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. 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 iconv1 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. 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 TERM7 environment variable, it does not use terminfo3 or termcap3. It instead uses TerminalCapabilities3. 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 vi1, 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 setterm1 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. 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. Jonathan de Boyne Pollard