diff options
Diffstat (limited to 'doc/options.rst')
| -rw-r--r-- | doc/options.rst | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/doc/options.rst b/doc/options.rst new file mode 100644 index 000000000000..9219037dcd37 --- /dev/null +++ b/doc/options.rst @@ -0,0 +1,164 @@ + +.. index:: --libxo +.. index:: Options + +.. _options: + +Command-line Arguments +====================== + +libxo uses command line options to trigger rendering behavior. There +are multiple conventions for passing options, all using the +"`--libxo`" option:: + + --libxo <options> + --libxo=<options> + --libxo:<brief-options> + +The *brief-options* is a series of single letter abbrevations, where +the *options* is a comma-separated list of words. Both provide access +to identical functionality. The following invocations are all +identical in outcome:: + + my-app --libxo warn,pretty arg1 + my-app --libxo=warn,pretty arg1 + my-app --libxo:WP arg1 + +Programs using libxo are expecting to call the xo_parse_args function +to parse these arguments. See :ref:`xo_parse_args` for details. + +Option Keywords +--------------- + +Options is a comma-separated list of tokens that correspond to output +styles, flags, or features: + +=============== ======================================================= +Token Action +=============== ======================================================= +color Enable colors/effects for display styles (TEXT, HTML) +colors=xxxx Adjust color output values +dtrt Enable "Do The Right Thing" mode +flush Flush after every libxo function call +flush-line Flush after every line (line-buffered) +html Emit HTML output +indent=xx Set the indentation level +info Add info attributes (HTML) +json Emit JSON output +keys Emit the key attribute for keys (XML) +log-gettext Log (via stderr) each gettext(3) string lookup +log-syslog Log (via stderr) each syslog message (via xo_syslog) +no-humanize Ignore the {h:} modifier (TEXT, HTML) +no-locale Do not initialize the locale setting +no-retain Prevent retaining formatting information +no-top Do not emit a top set of braces (JSON) +not-first Pretend the 1st output item was not 1st (JSON) +pretty Emit pretty-printed output +retain Force retaining formatting information +text Emit TEXT output +underscores Replace XML-friendly "-"s with JSON friendly "_"s +units Add the 'units' (XML) or 'data-units (HTML) attribute +warn Emit warnings when libxo detects bad calls +warn-xml Emit warnings in XML +xml Emit XML output +xpath Add XPath expressions (HTML) +=============== ======================================================= + +Most of these option are simple and direct, but some require +additional details: + +- "colors" is described in :ref:`color-mapping`. +- "flush-line" performs line buffering, even when the output is not + directed to a TTY device. +- "info" generates additional data for HTML, encoded in attributes + using names that state with "data-". +- "keys" adds a "key" attribute for XML output to indicate that a leaf + is an identifier for the list member. +- "no-humanize" avoids "humanizing" numeric output (see + :ref:`humanize-modifier` for details). +- "no-locale" instructs libxo to avoid translating output to the + current locale. +- "no-retain" disables the ability of libxo to internally retain + "compiled" information about formatting strings (see :ref:`retain` + for details). +- "underscores" can be used with JSON output to change XML-friendly + names with dashes into JSON-friendly name with underscores. +- "warn" allows libxo to emit warnings on stderr when application code + make incorrect calls. +- "warn-xml" causes those warnings to be placed in XML inside the + output. + +Brief Options +------------- + +The brief options are simple single-letter aliases to the normal +keywords, as detailed below: + +======== ============================================= + Option Action +======== ============================================= + c Enable color/effects for TEXT/HTML + F Force line-buffered flushing + H Enable HTML output (XO_STYLE_HTML) + I Enable info output (XOF_INFO) + i<num> Indent by <number> + J Enable JSON output (XO_STYLE_JSON) + k Add keys to XPATH expressions in HTML + n Disable humanization (TEXT, HTML) + P Enable pretty-printed output (XOF_PRETTY) + T Enable text output (XO_STYLE_TEXT) + U Add units to HTML output + u Change "-"s to "_"s in element names (JSON) + W Enable warnings (XOF_WARN) + X Enable XML output (XO_STYLE_XML) + x Enable XPath data (XOF_XPATH) +======== ============================================= + +.. index:: Colors + +.. _color-mapping: + +Color Mapping +------------- + +The "colors" option takes a value that is a set of mappings from the +pre-defined set of colors to new foreground and background colors. +The value is a series of "fg/bg" values, separated by a "+". Each +pair of "fg/bg" values gives the colors to which a basic color is +mapped when used as a foreground or background color. The order is +the mappings is: + +- black +- red +- green +- yellow +- blue +- magenta +- cyan +- white + +Pairs may be skipped, leaving them mapped as normal, as are missing +pairs or single colors. + +For example consider the following xo_emit call:: + + xo_emit("{C:fg-red,bg-green}Merry XMas!!{C:}\n"); + +To turn all colored output to red-on-blue, use eight pairs of +"red/blue" mappings separated by "+"s:: + + --libxo colors=red/blue+red/blue+red/blue+red/blue+\ + red/blue+red/blue+red/blue+red/blue + +To turn the red-on-green text to magenta-on-cyan, give a "magenta" +foreground value for red (the second mapping) and a "cyan" background +to green (the third mapping):: + + --libxo colors=+magenta+/cyan + +Consider the common situation where blue output looks unreadable on a +terminal session with a black background. To turn both "blue" +foreground and background output to "yellow", give only the fifth +mapping, skipping the first four mappings with bare "+"s:: + + --libxo colors=++++yellow/yellow |