contrib/libxo/doc/options.rst

   1
   2 .. index:: --libxo
   3 .. index:: Options
   4
   5 .. _options:
   6
   7 Command-line Arguments
   8 ======================
   9
  10 libxo uses command line options to trigger rendering behavior.  There
  11 are multiple conventions for passing options, all using the
  12 "`--libxo`" option::
  13
  14   --libxo <options>
  15   --libxo=<options>
  16   --libxo:<brief-options>
  17
  18 The *brief-options* is a series of single letter abbrevations, where
  19 the *options* is a comma-separated list of words.  Both provide access
  20 to identical functionality.  The following invocations are all
  21 identical in outcome::
  22
  23   my-app --libxo warn,pretty arg1
  24   my-app --libxo=warn,pretty arg1
  25   my-app --libxo:WP arg1
  26
  27 Programs using libxo are expecting to call the xo_parse_args function
  28 to parse these arguments.  See :ref:`xo_parse_args` for details.
  29
  30 Option Keywords
  31 ---------------
  32
  33 Options is a comma-separated list of tokens that correspond to output
  34 styles, flags, or features:
  35
  36 =============== =======================================================
  37 Token           Action
  38 =============== =======================================================
  39 color           Enable colors/effects for display styles (TEXT, HTML)
  40 colors=xxxx     Adjust color output values
  41 dtrt            Enable "Do The Right Thing" mode
  42 flush           Flush after every libxo function call
  43 flush-line      Flush after every line (line-buffered)
  44 html            Emit HTML output
  45 indent=xx       Set the indentation level
  46 info            Add info attributes (HTML)
  47 json            Emit JSON output
  48 keys            Emit the key attribute for keys (XML)
  49 log-gettext     Log (via stderr) each gettext(3) string lookup
  50 log-syslog      Log (via stderr) each syslog message (via xo_syslog)
  51 no-humanize     Ignore the {h:} modifier (TEXT, HTML)
  52 no-locale       Do not initialize the locale setting
  53 no-retain       Prevent retaining formatting information
  54 no-top          Do not emit a top set of braces (JSON)
  55 not-first       Pretend the 1st output item was not 1st (JSON)
  56 pretty          Emit pretty-printed output
  57 retain          Force retaining formatting information
  58 text            Emit TEXT output
  59 underscores     Replace XML-friendly "-"s with JSON friendly "_"s
  60 units           Add the 'units' (XML) or 'data-units (HTML) attribute
  61 warn            Emit warnings when libxo detects bad calls
  62 warn-xml        Emit warnings in XML
  63 xml             Emit XML output
  64 xpath           Add XPath expressions (HTML)
  65 =============== =======================================================
  66
  67 Most of these option are simple and direct, but some require
  68 additional details:
  69
  70 - "colors" is described in :ref:`color-mapping`.
  71 - "flush-line" performs line buffering, even when the output is not
  72   directed to a TTY device.
  73 - "info" generates additional data for HTML, encoded in attributes
  74   using names that state with "data-".
  75 - "keys" adds a "key" attribute for XML output to indicate that a leaf
  76   is an identifier for the list member.
  77 - "no-humanize" avoids "humanizing" numeric output (see
  78   :ref:`humanize-modifier` for details).
  79 - "no-locale" instructs libxo to avoid translating output to the
  80   current locale.
  81 - "no-retain" disables the ability of libxo to internally retain
  82   "compiled" information about formatting strings (see :ref:`retain`
  83   for details).
  84 - "underscores" can be used with JSON output to change XML-friendly
  85   names with dashes into JSON-friendly name with underscores.
  86 - "warn" allows libxo to emit warnings on stderr when application code
  87   make incorrect calls.
  88 - "warn-xml" causes those warnings to be placed in XML inside the
  89   output.
  90
  91 Brief Options
  92 -------------
  93
  94 The brief options are simple single-letter aliases to the normal
  95 keywords, as detailed below:
  96
  97 ======== =============================================
  98  Option   Action
  99 ======== =============================================
 100  c        Enable color/effects for TEXT/HTML
 101  F        Force line-buffered flushing
 102  H        Enable HTML output (XO_STYLE_HTML)
 103  I        Enable info output (XOF_INFO)
 104  i<num>   Indent by <number>
 105  J        Enable JSON output (XO_STYLE_JSON)
 106  k        Add keys to XPATH expressions in HTML
 107  n        Disable humanization (TEXT, HTML)
 108  P        Enable pretty-printed output (XOF_PRETTY)
 109  T        Enable text output (XO_STYLE_TEXT)
 110  U        Add units to HTML output
 111  u        Change "-"s to "_"s in element names (JSON)
 112  W        Enable warnings (XOF_WARN)
 113  X        Enable XML output (XO_STYLE_XML)
 114  x        Enable XPath data (XOF_XPATH)
 115 ======== =============================================
 116
 117 .. index:: Colors
 118
 119 .. _color-mapping:
 120
 121 Color Mapping
 122 -------------
 123
 124 The "colors" option takes a value that is a set of mappings from the
 125 pre-defined set of colors to new foreground and background colors.
 126 The value is a series of "fg/bg" values, separated by a "+".  Each
 127 pair of "fg/bg" values gives the colors to which a basic color is
 128 mapped when used as a foreground or background color.  The order is
 129 the mappings is:
 130
 131 - black
 132 - red
 133 - green
 134 - yellow
 135 - blue
 136 - magenta
 137 - cyan
 138 - white
 139
 140 Pairs may be skipped, leaving them mapped as normal, as are missing
 141 pairs or single colors.
 142
 143 For example consider the following xo_emit call::
 144
 145     xo_emit("{C:fg-red,bg-green}Merry XMas!!{C:}\n");
 146
 147 To turn all colored output to red-on-blue, use eight pairs of
 148 "red/blue" mappings separated by "+"s::
 149
 150     --libxo colors=red/blue+red/blue+red/blue+red/blue+\
 151                    red/blue+red/blue+red/blue+red/blue
 152
 153 To turn the red-on-green text to magenta-on-cyan, give a "magenta"
 154 foreground value for red (the second mapping) and a "cyan" background
 155 to green (the third mapping)::
 156
 157     --libxo colors=+magenta+/cyan
 158
 159 Consider the common situation where blue output looks unreadable on a
 160 terminal session with a black background.  To turn both "blue"
 161 foreground and background output to "yellow", give only the fifth
 162 mapping, skipping the first four mappings with bare "+"s::
 163
 164     --libxo colors=++++yellow/yellow