with class "text"::
+
+ EXAMPLE:
+ xo_emit("The hat is {:size/%s}.\n", size_val);
+ TEXT:
+ The hat is extra small.
+ XML:
+
.
+
+.. index:: errno
+
+"%m" Is Supported
+~~~~~~~~~~~~~~~~~
+
+libxo supports the '%m' directive, which formats the error message
+associated with the current value of "errno". It is the equivalent
+of "%s" with the argument strerror(errno)::
+
+ xo_emit("{:filename} cannot be opened: {:error/%m}", filename);
+ xo_emit("{:filename} cannot be opened: {:error/%s}",
+ filename, strerror(errno));
+
+"%n" Is Not Supported
+~~~~~~~~~~~~~~~~~~~~~
+
+libxo does not support the '%n' directive. It's a bad idea and we
+just don't do it.
+
+The Encoding Format (eformat)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The "eformat" string is the format string used when encoding the field
+for JSON and XML. If not provided, it defaults to the primary format
+with any minimum width removed. If the primary is not given, both
+default to "%s".
+
+Content Strings
+~~~~~~~~~~~~~~~
+
+For padding and labels, the content string is considered the content,
+unless a format is given.
+
+.. index:: printf-like
+
+Argument Validation
+~~~~~~~~~~~~~~~~~~~
+
+Many compilers and tool chains support validation of printf-like
+arguments. When the format string fails to match the argument list,
+a warning is generated. This is a valuable feature and while the
+formatting strings for libxo differ considerably from printf, many of
+these checks can still provide build-time protection against bugs.
+
+libxo provide variants of functions that provide this ability, if the
+"--enable-printflike" option is passed to the "configure" script.
+These functions use the "_p" suffix, like "xo_emit_p()",
+xo_emit_hp()", etc.
+
+The following are features of libxo formatting strings that are
+incompatible with printf-like testing:
+
+- implicit formats, where "{:tag}" has an implicit "%s";
+- the "max" parameter for strings, where "{:tag/%4.10.6s}" means up to
+ ten bytes of data can be inspected to fill a minimum of 4 columns and
+ a maximum of 6;
+- percent signs in strings, where "{:filled}%" makes a single,
+ trailing percent sign;
+- the "l" and "h" modifiers for strings, where "{:tag/%hs}" means
+ locale-based string and "{:tag/%ls}" means a wide character string;
+- distinct encoding formats, where "{:tag/#%s/%s}" means the display
+ styles (text and HTML) will use "#%s" where other styles use "%s";
+
+If none of these features are in use by your code, then using the "_p"
+variants might be wise:
+
+================== ========================
+ Function printf-like Equivalent
+================== ========================
+ xo_emit_hv xo_emit_hvp
+ xo_emit_h xo_emit_hp
+ xo_emit xo_emit_p
+ xo_emit_warn_hcv xo_emit_warn_hcvp
+ xo_emit_warn_hc xo_emit_warn_hcp
+ xo_emit_warn_c xo_emit_warn_cp
+ xo_emit_warn xo_emit_warn_p
+ xo_emit_warnx xo_emit_warnx_p
+ xo_emit_err xo_emit_err_p
+ xo_emit_errx xo_emit_errx_p
+ xo_emit_errc xo_emit_errc_p
+================== ========================
+
+.. index:: performance
+.. index:: XOEF_RETAIN
+
+.. _retain:
+
+Retaining Parsed Format Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+libxo can retain the parsed internal information related to the given
+format string, allowing subsequent xo_emit calls, the retained
+information is used, avoiding repetitive parsing of the format string::
+
+ SYNTAX:
+ int xo_emit_f(xo_emit_flags_t flags, const char fmt, ...);
+ EXAMPLE:
+ xo_emit_f(XOEF_RETAIN, "{:some/%02d}{:thing/%-6s}{:fancy}\n",
+ some, thing, fancy);
+
+To retain parsed format information, use the XOEF_RETAIN flag to the
+xo_emit_f() function. A complete set of xo_emit_f functions exist to
+match all the xo_emit function signatures (with handles, varadic
+argument, and printf-like flags):
+
+================== ========================
+ Function Flags Equivalent
+================== ========================
+ xo_emit_hv xo_emit_hvf
+ xo_emit_h xo_emit_hf
+ xo_emit xo_emit_f
+ xo_emit_hvp xo_emit_hvfp
+ xo_emit_hp xo_emit_hfp
+ xo_emit_p xo_emit_fp
+================== ========================
+
+The format string must be immutable across multiple calls to xo_emit_f(),
+since the library retains the string. Typically this is done by using
+static constant strings, such as string literals. If the string is not
+immutable, the XOEF_RETAIN flag must not be used.
+
+The functions xo_retain_clear() and xo_retain_clear_all() release
+internal information on either a single format string or all format
+strings, respectively. Neither is required, but the library will
+retain this information until it is cleared or the process exits::
+
+ const char *fmt = "{:name} {:count/%d}\n";
+ for (i = 0; i < 1000; i++) {
+ xo_open_instance("item");
+ xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
+ }
+ xo_retain_clear(fmt);
+
+The retained information is kept as thread-specific data.
+
+Example
+~~~~~~~
+
+In this example, the value for the number of items in stock is emitted::
+
+ xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n",
+ instock);
+
+This call will generate the following output::
+
+ TEXT:
+ In stock: 144
+ XML:
+
+
+Clearly HTML wins the verbosity award, and this output does
+not include XOF_XPATH or XOF_INFO data, which would expand the
+penultimate line to::
+
+
diff --git a/doc/field-modifiers.rst b/doc/field-modifiers.rst
new file mode 100644
index 000000000000..9c8f2cdac89c
--- /dev/null
+++ b/doc/field-modifiers.rst
@@ -0,0 +1,353 @@
+
+.. index:: Field Modifiers
+.. _field-modifiers:
+
+Field Modifiers
+~~~~~~~~~~~~~~~
+
+Field modifiers are flags which modify the way content emitted for
+particular output styles:
+
+=== =============== ===================================================
+ M Name Description
+=== =============== ===================================================
+ a argument The content appears as a 'const char \*' argument
+ c colon A colon (":") is appended after the label
+ d display Only emit field for display styles (text/HTML)
+ e encoding Only emit for encoding styles (XML/JSON)
+ g gettext Call gettext on field's render content
+ h humanize (hn) Format large numbers in human-readable style
+\ hn-space Humanize: Place space between numeric and unit
+\ hn-decimal Humanize: Add a decimal digit, if number < 10
+\ hn-1000 Humanize: Use 1000 as divisor instead of 1024
+ k key Field is a key, suitable for XPath predicates
+ l leaf-list Field is a leaf-list
+ n no-quotes Do not quote the field when using JSON style
+ p plural Gettext: Use comma-separated plural form
+ q quotes Quote the field when using JSON style
+ t trim Trim leading and trailing whitespace
+ w white A blank (" ") is appended after the label
+=== =============== ===================================================
+
+Roles and modifiers can also use more verbose names, when preceded by
+a comma. For example, the modifier string "Lwc" (or "L,white,colon")
+means the field has a label role (text that describes the next field)
+and should be followed by a colon ('c') and a space ('w'). The
+modifier string "Vkq" (or ":key,quote") means the field has a value
+role (the default role), that it is a key for the current instance,
+and that the value should be quoted when encoded for JSON.
+
+.. index:: Field Modifiers; Argument
+.. _argument-modifier:
+
+The Argument Modifier ({a:})
+++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Argument
+
+The argument modifier indicates that the content of the field
+descriptor will be placed as a UTF-8 string (const char \*) argument
+within the xo_emit parameters::
+
+ EXAMPLE:
+ xo_emit("{La:} {a:}\n", "Label text", "label", "value");
+ TEXT:
+ Label text value
+ JSON:
+ "label": "value"
+ XML:
+
+
+The argument modifier allows field names for value fields to be passed
+on the stack, avoiding the need to build a field descriptor using
+snprintf. For many field roles, the argument modifier is not needed,
+since those roles have specific mechanisms for arguments, such as
+"{C:fg-%s}".
+
+.. index:: Field Modifiers; Colon
+.. _colon-modifier:
+
+The Colon Modifier ({c:})
++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Colon
+
+The colon modifier appends a single colon to the data value::
+
+ EXAMPLE:
+ xo_emit("{Lc:Name}{:name}\n", "phil");
+ TEXT:
+ Name:phil
+
+The colon modifier is only used for the TEXT and HTML output
+styles. It is commonly combined with the space modifier ('{w:}').
+It is purely a convenience feature.
+
+.. index:: Field Modifiers; Display
+.. _display-modifier:
+
+The Display Modifier ({d:})
++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Display
+
+The display modifier indicated the field should only be generated for
+the display output styles, TEXT and HTML::
+
+ EXAMPLE:
+ xo_emit("{Lcw:Name}{d:name} {:id/%d}\n", "phil", 1);
+ TEXT:
+ Name: phil 1
+ XML:
+
+
+The display modifier is the opposite of the encoding modifier, and
+they are often used to give to distinct views of the underlying data.
+
+.. index:: Field Modifiers; Encoding
+.. _encoding-modifier:
+
+The Encoding Modifier ({e:})
+++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Encoding
+
+The display modifier indicated the field should only be generated for
+the display output styles, TEXT and HTML::
+
+ EXAMPLE:
+ xo_emit("{Lcw:Name}{:name} {e:id/%d}\n", "phil", 1);
+ TEXT:
+ Name: phil
+ XML:
+
+
+The encoding modifier is the opposite of the display modifier, and
+they are often used to give to distinct views of the underlying data.
+
+.. index:: Field Modifiers; Gettext
+.. _gettext-modifier:
+
+The Gettext Modifier ({g:})
++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Gettext
+.. index:: gettext
+
+The gettext modifier is used to translate individual fields using the
+gettext domain (typically set using the "`{G:}`" role) and current
+language settings. Once libxo renders the field value, it is passed
+to gettext(3), where it is used as a key to find the native language
+translation.
+
+In the following example, the strings "State" and "full" are passed
+to gettext() to find locale-based translated strings::
+
+ xo_emit("{Lgwc:State}{g:state}\n", "full");
+
+See :ref:`gettext-role`, :ref:`plural-modifier`, and
+:ref:`i18n` for additional details.
+
+.. index:: Field Modifiers; Humanize
+.. _humanize-modifier:
+
+The Humanize Modifier ({h:})
+++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Humanize
+
+The humanize modifier is used to render large numbers as in a
+human-readable format. While numbers like "44470272" are completely
+readable to computers and savants, humans will generally find "44M"
+more meaningful.
+
+"hn" can be used as an alias for "humanize".
+
+The humanize modifier only affects display styles (TEXT and HMTL).
+The "`no-humanize`" option (See :ref:`options`) will block
+the function of the humanize modifier.
+
+There are a number of modifiers that affect details of humanization.
+These are only available in as full names, not single characters. The
+"`hn-space`" modifier places a space between the number and any
+multiplier symbol, such as "M" or "K" (ex: "44 K"). The
+"`hn-decimal`" modifier will add a decimal point and a single tenths
+digit when the number is less than 10 (ex: "4.4K"). The "`hn-1000`"
+modifier will use 1000 as divisor instead of 1024, following the
+JEDEC-standard instead of the more natural binary powers-of-two
+tradition::
+
+ EXAMPLE:
+ xo_emit("{h:input/%u}, {h,hn-space:output/%u}, "
+ "{h,hn-decimal:errors/%u}, {h,hn-1000:capacity/%u}, "
+ "{h,hn-decimal:remaining/%u}\n",
+ input, output, errors, capacity, remaining);
+ TEXT:
+ 21, 57 K, 96M, 44M, 1.2G
+
+In the HTML style, the original numeric value is rendered in the
+"data-number" attribute on the
element::
+
+
96M
+
+.. index:: Field Modifiers; Key
+.. _key-modifier:
+
+The Key Modifier ({k:})
++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Key
+
+The key modifier is used to indicate that a particular field helps
+uniquely identify an instance of list data::
+
+ EXAMPLE:
+ xo_open_list("user");
+ for (i = 0; i < num_users; i++) {
+ xo_open_instance("user");
+ xo_emit("User {k:name} has {:count} tickets\n",
+ user[i].u_name, user[i].u_tickets);
+ xo_close_instance("user");
+ }
+ xo_close_list("user");
+
+.. index:: XOF_XPATH
+
+Currently the key modifier is only used when generating XPath value
+for the HTML output style when XOF_XPATH is set, but other uses are
+likely in the near future.
+
+.. index:: Field Modifiers; Leaf-List
+.. _leaf-list:
+
+The Leaf-List Modifier ({l:})
++++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Leaf-List
+
+The leaf-list modifier is used to distinguish lists where each
+instance consists of only a single value. In XML, these are
+rendered as single elements, where JSON renders them as arrays::
+
+ EXAMPLE:
+ for (i = 0; i < num_users; i++) {
+ xo_emit("Member {l:user}\n", user[i].u_name);
+ }
+ XML:
+
phil
+
pallavi
+ JSON:
+ "user": [ "phil", "pallavi" ]
+
+The name of the field must match the name of the leaf list.
+
+.. index:: Field Modifiers; No-Quotes
+.. _no-quotes-modifier:
+
+The No-Quotes Modifier ({n:})
++++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; No-Quotes
+
+The no-quotes modifier (and its twin, the 'quotes' modifier) affect
+the quoting of values in the JSON output style. JSON uses quotes for
+string value, but no quotes for numeric, boolean, and null data.
+xo_emit applies a simple heuristic to determine whether quotes are
+needed, but often this needs to be controlled by the caller::
+
+ EXAMPLE:
+ const char *bool = is_true ? "true" : "false";
+ xo_emit("{n:fancy/%s}", bool);
+ JSON:
+ "fancy": true
+
+.. index:: Field Modifiers; Plural
+.. _plural-modifier:
+
+The Plural Modifier ({p:})
+++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Plural
+.. index:: gettext
+
+The plural modifier selects the appropriate plural form of an
+expression based on the most recent number emitted and the current
+language settings. The contents of the field should be the singular
+and plural English values, separated by a comma::
+
+ xo_emit("{:bytes} {Ngp:byte,bytes}\n", bytes);
+
+The plural modifier is meant to work with the gettext modifier ({g:})
+but can work independently. See :ref:`gettext-modifier`.
+
+When used without the gettext modifier or when the message does not
+appear in the message catalog, the first token is chosen when the last
+numeric value is equal to 1; otherwise the second value is used,
+mimicking the simple pluralization rules of English.
+
+When used with the gettext modifier, the ngettext(3) function is
+called to handle the heavy lifting, using the message catalog to
+convert the singular and plural forms into the native language.
+
+.. index:: Field Modifiers; Quotes
+.. _quotes-modifier:
+
+The Quotes Modifier ({q:})
+++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Quotes
+
+The quotes modifier (and its twin, the 'no-quotes' modifier) affect
+the quoting of values in the JSON output style. JSON uses quotes for
+string value, but no quotes for numeric, boolean, and null data.
+xo_emit applies a simple heuristic to determine whether quotes are
+needed, but often this needs to be controlled by the caller::
+
+ EXAMPLE:
+ xo_emit("{q:time/%d}", 2014);
+ JSON:
+ "year": "2014"
+
+The heuristic is based on the format; if the format uses any of the
+following conversion specifiers, then no quotes are used::
+
+ d i o u x X D O U e E f F g G a A c C p
+
+.. index:: Field Modifiers; Trim
+.. _trim-modifier:
+
+The Trim Modifier ({t:})
+++++++++++++++++++++++++
+
+.. index:: Field Modifiers; Trim
+
+The trim modifier removes any leading or trailing whitespace from
+the value::
+
+ EXAMPLE:
+ xo_emit("{t:description}", " some input ");
+ JSON:
+ "description": "some input"
+
+.. index:: Field Modifiers; White Space
+.. _white-space-modifier:
+
+The White Space Modifier ({w:})
++++++++++++++++++++++++++++++++
+
+.. index:: Field Modifiers; White Space
+
+The white space modifier appends a single space to the data value::
+
+ EXAMPLE:
+ xo_emit("{Lw:Name}{:name}\n", "phil");
+ TEXT:
+ Name phil
+
+The white space modifier is only used for the TEXT and HTML output
+styles. It is commonly combined with the colon modifier ('{c:}').
+It is purely a convenience feature.
+
+Note that the sense of the 'w' modifier is reversed for the units role
+({Uw:}); a blank is added before the contents, rather than after it.
diff --git a/doc/field-roles.rst b/doc/field-roles.rst
new file mode 100644
index 000000000000..81f890b493b3
--- /dev/null
+++ b/doc/field-roles.rst
@@ -0,0 +1,310 @@
+
+.. index:: Field Roles
+.. _field-roles:
+
+Field Roles
+~~~~~~~~~~~
+
+Field roles are optional, and indicate the role and formatting of the
+content. The roles are listed below; only one role is permitted:
+
+=== ============== =================================================
+R Name Description
+=== ============== =================================================
+C color Field has color and effect controls
+D decoration Field is non-text (e.g., colon, comma)
+E error Field is an error message
+G gettext Call gettext(3) on the format string
+L label Field is text that prefixes a value
+N note Field is text that follows a value
+P padding Field is spaces needed for vertical alignment
+T title Field is a title value for headings
+U units Field is the units for the previous value field
+V value Field is the name of field (the default)
+W warning Field is a warning message
+[ start-anchor Begin a section of anchored variable-width text
+] stop-anchor End a section of anchored variable-width text
+=== ============== =================================================
+
+ EXAMPLE:
+ xo_emit("{L:Free}{D::}{P: }{:free/%u} {U:Blocks}\n",
+ free_blocks);
+
+When a role is not provided, the "*value*" role is used as the default.
+
+Roles and modifiers can also use more verbose names, when preceded by
+a comma::
+
+ EXAMPLE:
+ xo_emit("{,label:Free}{,decoration::}{,padding: }"
+ "{,value:free/%u} {,units:Blocks}\n",
+ free_blocks);
+
+.. index:: Field Roles; Color
+.. _color-role:
+
+The Color Role ({C:})
++++++++++++++++++++++
+
+Colors and effects control how text values are displayed; they are
+used for display styles (TEXT and HTML)::
+
+ xo_emit("{C:bold}{:value}{C:no-bold}\n", value);
+
+Colors and effects remain in effect until modified by other "C"-role
+fields::
+
+ xo_emit("{C:bold}{C:inverse}both{C:no-bold}only inverse\n");
+
+If the content is empty, the "*reset*" action is performed::
+
+ xo_emit("{C:both,underline}{:value}{C:}\n", value);
+
+The content should be a comma-separated list of zero or more colors or
+display effects::
+
+ xo_emit("{C:bold,inverse}Ugly{C:no-bold,no-inverse}\n");
+
+The color content can be either static, when placed directly within
+the field descriptor, or a printf-style format descriptor can be used,
+if preceded by a slash ("/"):
+
+ xo_emit("{C:/%s%s}{:value}{C:}", need_bold ? "bold" : "",
+ need_underline ? "underline" : "", value);
+
+Color names are prefixed with either "fg-" or "bg-" to change the
+foreground and background colors, respectively::
+
+ xo_emit("{C:/fg-%s,bg-%s}{Lwc:Cost}{:cost/%u}{C:reset}\n",
+ fg_color, bg_color, cost);
+
+The following table lists the supported effects:
+
+=============== =================================================
+ Name Description
+=============== =================================================
+ bg-XXXXX Change background color
+ bold Start bold text effect
+ fg-XXXXX Change foreground color
+ inverse Start inverse (aka reverse) text effect
+ no-bold Stop bold text effect
+ no-inverse Stop inverse (aka reverse) text effect
+ no-underline Stop underline text effect
+ normal Reset effects (only)
+ reset Reset colors and effects (restore defaults)
+ underline Start underline text effect
+=============== =================================================
+
+The following color names are supported:
+
+========= ============================================
+ Name Description
+========= ============================================
+ black
+ blue
+ cyan
+ default Default color for foreground or background
+ green
+ magenta
+ red
+ white
+ yellow
+========= ============================================
+
+When using colors, the developer should remember that users will
+change the foreground and background colors of terminal session
+according to their own tastes, so assuming that "blue" looks nice is
+never safe, and is a constant annoyance to your dear author. In
+addition, a significant percentage of users (1 in 12) will be color
+blind. Depending on color to convey critical information is not a
+good idea. Color should enhance output, but should not be used as the
+sole means of encoding information.
+
+.. index:: Field Roles; Decoration
+.. _decoration-role:
+
+The Decoration Role ({D:})
+++++++++++++++++++++++++++
+
+Decorations are typically punctuation marks such as colons,
+semi-colons, and commas used to decorate the text and make it simpler
+for human readers. By marking these distinctly, HTML usage scenarios
+can use CSS to direct their display parameters::
+
+ xo_emit("{D:((}{:name}{D:))}\n", name);
+
+.. index:: Field Roles; Gettext
+.. _gettext-role:
+
+The Gettext Role ({G:})
++++++++++++++++++++++++
+
+libxo supports internationalization (i18n) through its use of
+gettext(3). Use the "{G:}" role to request that the remaining part of
+the format string, following the "{G:}" field, be handled using
+gettext().
+
+Since gettext() uses the string as the key into the message catalog,
+libxo uses a simplified version of the format string that removes
+unimportant field formatting and modifiers, stopping minor formatting
+changes from impacting the expensive translation process. A developer
+change such as changing "/%06d" to "/%08d" should not force hand
+inspection of all .po files.
+
+The simplified version can be generated for a single message using the
+"`xopo -s $text`" command, or an entire .pot can be translated using
+the "`xopo -f $input -o $output`" command.
+
+ xo_emit("{G:}Invalid token\n");
+
+The {G:} role allows a domain name to be set. gettext calls will
+continue to use that domain name until the current format string
+processing is complete, enabling a library function to emit strings
+using it's own catalog. The domain name can be either static as the
+content of the field, or a format can be used to get the domain name
+from the arguments.
+
+ xo_emit("{G:libc}Service unavailable in restricted mode\n");
+
+See :ref:`i18n` for additional details.
+
+.. index:: Field Roles; Label
+.. _label-role:
+
+The Label Role ({L:})
++++++++++++++++++++++
+
+Labels are text that appears before a value::
+
+ xo_emit("{Lwc:Cost}{:cost/%u}\n", cost);
+
+.. index:: Field Roles; Note
+.. _note-role:
+
+The Note Role ({N:})
+++++++++++++++++++++
+
+Notes are text that appears after a value::
+
+ xo_emit("{:cost/%u} {N:per year}\n", cost);
+
+.. index:: Field Roles; Padding
+.. _padding-role:
+
+The Padding Role ({P:})
++++++++++++++++++++++++
+
+Padding represents whitespace used before and between fields.
+
+The padding content can be either static, when placed directly within
+the field descriptor, or a printf-style format descriptor can be used,
+if preceded by a slash ("/")::
+
+ xo_emit("{P: }{Lwc:Cost}{:cost/%u}\n", cost);
+ xo_emit("{P:/%30s}{Lwc:Cost}{:cost/%u}\n", "", cost);
+
+.. index:: Field Roles; Title
+.. _title-role:
+
+The Title Role ({T:})
++++++++++++++++++++++
+
+Title are heading or column headers that are meant to be displayed to
+the user. The title can be either static, when placed directly within
+the field descriptor, or a printf-style format descriptor can be used,
+if preceded by a slash ("/")::
+
+ xo_emit("{T:Interface Statistics}\n");
+ xo_emit("{T:/%20.20s}{T:/%6.6s}\n", "Item Name", "Cost");
+
+Title fields have an extra convenience feature; if both content and
+format are specified, instead of looking to the argument list for a
+value, the content is used, allowing a mixture of format and content
+within the field descriptor::
+
+ xo_emit("{T:Name/%20s}{T:Count/%6s}\n");
+
+Since the incoming argument is a string, the format must be "%s" or
+something suitable.
+
+.. index:: Field Roles; Units
+.. index:: XOF_UNITS
+.. _units-role:
+
+The Units Role ({U:})
++++++++++++++++++++++
+
+Units are the dimension by which values are measured, such as degrees,
+miles, bytes, and decibels. The units field carries this information
+for the previous value field::
+
+ xo_emit("{Lwc:Distance}{:distance/%u}{Uw:miles}\n", miles);
+
+Note that the sense of the 'w' modifier is reversed for units;
+a blank is added before the contents, rather than after it.
+
+When the XOF_UNITS flag is set, units are rendered in XML as the
+"units" attribute::
+
+
50
+
+Units can also be rendered in HTML as the "data-units" attribute::
+
+
50
+
+.. index:: Field Roles; Value
+.. _value-role:
+
+The Value Role ({V:} and {:})
++++++++++++++++++++++++++++++
+
+The value role is used to represent the a data value that is
+interesting for the non-display output styles (XML and JSON). Value
+is the default role; if no other role designation is given, the field
+is a value. The field name must appear within the field descriptor,
+followed by one or two format descriptors. The first format
+descriptor is used for display styles (TEXT and HTML), while the
+second one is used for encoding styles (XML and JSON). If no second
+format is given, the encoding format defaults to the first format,
+with any minimum width removed. If no first format is given, both
+format descriptors default to "%s"::
+
+ xo_emit("{:length/%02u}x{:width/%02u}x{:height/%02u}\n",
+ length, width, height);
+ xo_emit("{:author} wrote \"{:poem}\" in {:year/%4d}\n,
+ author, poem, year);
+
+.. index:: Field Roles; Anchor
+.. _anchor-role:
+
+The Anchor Roles ({[:} and {]:})
+++++++++++++++++++++++++++++++++
+
+The anchor roles allow a set of strings by be padded as a group,
+but still be visible to xo_emit as distinct fields. Either the start
+or stop anchor can give a field width and it can be either directly in
+the descriptor or passed as an argument. Any fields between the start
+and stop anchor are padded to meet the minimum width given.
+
+To give a width directly, encode it as the content of the anchor tag::
+
+ xo_emit("({[:10}{:min/%d}/{:max/%d}{]:})\n", min, max);
+
+To pass a width as an argument, use "%d" as the format, which must
+appear after the "/". Note that only "%d" is supported for widths.
+Using any other value could ruin your day::
+
+ xo_emit("({[:/%d}{:min/%d}/{:max/%d}{]:})\n", width, min, max);
+
+If the width is negative, padding will be added on the right, suitable
+for left justification. Otherwise the padding will be added to the
+left of the fields between the start and stop anchors, suitable for
+right justification. If the width is zero, nothing happens. If the
+number of columns of output between the start and stop anchors is less
+than the absolute value of the given width, nothing happens.
+
+.. index:: XOF_WARN
+
+Widths over 8k are considered probable errors and not supported. If
+XOF_WARN is set, a warning will be generated.
diff --git a/doc/format-strings.rst b/doc/format-strings.rst
new file mode 100644
index 000000000000..44e02abd41e7
--- /dev/null
+++ b/doc/format-strings.rst
@@ -0,0 +1,47 @@
+
+.. index:: Format Strings
+.. _format-strings:
+
+Format Strings
+--------------
+
+libxo uses format strings to control the rendering of data into the
+various output styles. Each format string contains a set of zero or
+more field descriptions, which describe independent data fields. Each
+field description contains a set of modifiers, a content string, and
+zero, one, or two format descriptors. The modifiers tell libxo what
+the field is and how to treat it, while the format descriptors are
+formatting instructions using printf-style format strings, telling
+libxo how to format the field. The field description is placed inside
+a set of braces, with a colon (":") after the modifiers and a slash
+("/") before each format descriptors. Text may be intermixed with
+field descriptions within the format string.
+
+The field description is given as follows::
+
+ '{' [ role | modifier ]* [',' long-names ]* ':' [ content ]
+ [ '/' field-format [ '/' encoding-format ]] '}'
+
+The role describes the function of the field, while the modifiers
+enable optional behaviors. The contents, field-format, and
+encoding-format are used in varying ways, based on the role. These
+are described in the following sections.
+
+In the following example, three field descriptors appear. The first
+is a padding field containing three spaces of padding, the second is a
+label ("In stock"), and the third is a value field ("in-stock"). The
+in-stock field has a "%u" format that will parse the next argument
+passed to the xo_emit function as an unsigned integer::
+
+ xo_emit("{P: }{Lwc:In stock}{:in-stock/%u}\n", 65);
+
+This single line of code can generate text (" In stock: 65\n"), XML
+("
65"), JSON ('"in-stock": 6'), or HTML (too
+lengthy to be listed here).
+
+While roles and modifiers typically use single character for brevity,
+there are alternative names for each which allow more verbose
+formatting strings. These names must be preceded by a comma, and may
+follow any single-character values::
+
+ xo_emit("{L,white,colon:In stock}{,key:in-stock/%u}\n", 65);
diff --git a/doc/formatting.rst b/doc/formatting.rst
new file mode 100644
index 000000000000..dbbdd24dfcc8
--- /dev/null
+++ b/doc/formatting.rst
@@ -0,0 +1,165 @@
+
+Formatting with libxo
+=====================
+
+Most unix commands emit text output aimed at humans. It is designed
+to be parsed and understood by a user. Humans are gifted at
+extracting details and pattern matching in such output. Often
+programmers need to extract information from this human-oriented
+output. Programmers use tools like grep, awk, and regular expressions
+to ferret out the pieces of information they need. Such solutions are
+fragile and require maintenance when output contents change or evolve,
+along with testing and validation.
+
+Modern tool developers favor encoding schemes like XML and JSON,
+which allow trivial parsing and extraction of data. Such formats are
+simple, well understood, hierarchical, easily parsed, and often
+integrate easier with common tools and environments. Changes to
+content can be done in ways that do not break existing users of the
+data, which can reduce maintenance costs and increase feature velocity.
+
+In addition, modern reality means that more output ends up in web
+browsers than in terminals, making HTML output valuable.
+
+libxo allows a single set of function calls in source code to generate
+traditional text output, as well as XML and JSON formatted data. HTML
+can also be generated; "
" elements surround the traditional text
+output, with attributes that detail how to render the data.
+
+A single libxo function call in source code is all that's required::
+
+ xo_emit("Connecting to {:host}.{:domain}...\n", host, domain);
+
+ TEXT:
+ Connecting to my-box.example.com...
+ XML:
+
my-box
+
example.com
+ JSON:
+ "host": "my-box",
+ "domain": "example.com"
+ HTML:
+
+
Connecting to
+
my-box
+
.
+
example.com
+
...
+
+
+Encoding Styles
+---------------
+
+There are four encoding styles supported by libxo:
+
+- TEXT output can be display on a terminal session, allowing
+ compatibility with traditional command line usage.
+- XML output is suitable for tools like XPath and protocols like
+ NETCONF.
+- JSON output can be used for RESTful APIs and integration with
+ languages like Javascript and Python.
+- HTML can be matched with a small CSS file to permit rendering in any
+ HTML5 browser.
+
+In general, XML and JSON are suitable for encoding data, while TEXT is
+suited for terminal output and HTML is suited for display in a web
+browser (see :ref:`xohtml`).
+
+Text Output
+~~~~~~~~~~~
+
+Most traditional programs generate text output on standard output,
+with contents like::
+
+ 36 ./src
+ 40 ./bin
+ 90 .
+
+In this example (taken from *du* source code), the code to generate this
+data might look like::
+
+ printf("%d\t%s\n", num_blocks, path);
+
+Simple, direct, obvious. But it's only making text output. Imagine
+using a single code path to make TEXT, XML, JSON or HTML, deciding at
+run time which to generate.
+
+libxo expands on the idea of printf format strings to make a single
+format containing instructions for creating multiple output styles::
+
+ xo_emit("{:blocks/%d}\t{:path/%s}\n", num_blocks, path);
+
+This line will generate the same text output as the earlier printf
+call, but also has enough information to generate XML, JSON, and HTML.
+
+The following sections introduce the other formats.
+
+XML Output
+~~~~~~~~~~
+
+XML output consists of a hierarchical set of elements, each encoded
+with a start tag and an end tag. The element should be named for data
+value that it is encoding::
+
+
-
+ 36
+ ./src
+
+
-
+ 40
+ ./bin
+
+
-
+ 90
+ .
+
+
+`XML`_ is the W3C standard for encoding data.
+
+.. _XML: https://w3c.org/TR/xml
+
+JSON Output
+~~~~~~~~~~~
+
+JSON output consists of a hierarchical set of objects and lists, each
+encoded with a quoted name, a colon, and a value. If the value is a
+string, it must be quoted, but numbers are not quoted. Objects are
+encoded using braces; lists are encoded using square brackets.
+Data inside objects and lists is separated using commas::
+
+ items: [
+ { "blocks": 36, "path" : "./src" },
+ { "blocks": 40, "path" : "./bin" },
+ { "blocks": 90, "path" : "./" }
+ ]
+
+HTML Output
+~~~~~~~~~~~
+
+HTML output is designed to allow the output to be rendered in a web
+browser with minimal effort. Each piece of output data is rendered
+inside a
element, with a class name related to the role of the
+data. By using a small set of class attribute values, a CSS
+stylesheet can render the HTML into rich text that mirrors the
+traditional text content.
+
+Additional attributes can be enabled to provide more details about the
+data, including data type, description, and an XPath location::
+
+
+
+
diff --git a/doc/getting.rst b/doc/getting.rst
new file mode 100644
index 000000000000..1511aada5a1e
--- /dev/null
+++ b/doc/getting.rst
@@ -0,0 +1,185 @@
+
+.. index:: Getting libxo
+
+Getting libxo
+=============
+
+libxo now ships as part of the FreeBSD Operating System (as of Release
+11).
+
+libxo source code lives on github:
+
+ https://github.com/Juniper/libxo
+
+The latest release of libxo is available at:
+
+ https://github.com/Juniper/libxo/releases
+
+We're using `Semantic Versioning`_ to number our releases. libxo is
+open source, distributed under the BSD license. We follow the
+branching scheme from `A Successful Git Branching Model`_:
+we do development under the "*develop*" branch, and release from
+the "*master*" branch. To clone a developer tree, run the following
+command::
+
+ git clone https://github.com/Juniper/libxo.git -b develop
+
+.. _Semantic Versioning: http://semver.org/spec/v2.0.0.html
+.. _A Successful Git Branching Model:
+ http://nvie.com/posts/a-successful-git-branching-model
+
+Issues, problems, and bugs should be directly to the issues page on
+our github site.
+
+Downloading libxo Source Code
+-----------------------------
+
+You can retrieve the source for libxo in two ways:
+
+A. Use a "distfile" for a specific release. We use github to maintain
+ our releases. Visit the `release page`_ to see the list of
+ releases. To download the latest, look for the release witeh the
+ green "Latest release" button and the green "libxo-RELEASE.tar.gz"
+ button under that section.
+
+.. _release page: https://github.com/Juniper/libxo/releases
+
+ After downloading that release's distfile, untar it as follows::
+
+ tar -zxf libxo-RELEASE.tar.gz
+ cd libxo-RELEASE
+
+ .. admonition:: Solaris Users
+
+ Note: for Solaris users, your "`tar`" command lacks the "-z" flag,
+ so you'll need to substitute "`gzip -dc $file | tar xf -`" instead
+ of "`tar -zxf $file`".
+
+B. Use the current build from github. This gives you the most recent
+ source code, which might be less stable than a specific release. To
+ build libxo from the git repo::
+
+ git clone https://github.com/Juniper/libxo.git
+ cd libxo
+
+ .. admonition:: Be Aware
+
+ The github repository does **not** contain the files generated by
+ "*autoreconf*", with the notable exception of the "*m4*" directory.
+ Since these files (depcomp, configure, missing, install-sh, etc) are
+ generated files, we keep them out of the source code repository.
+
+ This means that if you download the a release distfile, these files
+ will be ready and you'll just need to run "configure", but if you
+ download the source code from svn, then you'll need to run
+ "*autoreconf*" by hand. This step is done for you by the "*setup.sh*"
+ script, described in the next section.
+
+.. _building:
+
+Building libxo
+--------------
+
+To build libxo, you'll need to set up the build, run the "*configure*"
+script, run the "*make*" command, and run the regression tests.
+
+The following is a summary of the commands needed. These commands are
+explained in detail in the rest of this section::
+
+ sh bin/setup.sh
+ cd build
+ ../configure
+ make
+ make test
+ sudo make install
+
+The following sections will walk through each of these steps with
+additional details and options, but the above directions should be all
+that's needed.
+
+Setting up the build
+~~~~~~~~~~~~~~~~~~~~
+
+.. admonition: Note
+
+ If you downloaded a distfile, you can skip this step.
+
+Run the "*setup.sh*" script to set up the build. This script runs the
+"*autoreconf*" command to generate the "*configure*" script and other
+generated files::
+
+ sh bin/setup.sh
+
+Note: We're are currently using autoreconf version 2.69.
+
+Running the "configure" Script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Configure (and autoconf in general) provides a means of building
+software in diverse environments. Our configure script supports
+a set of options that can be used to adjust to your operating
+environment. Use "`configure --help`" to view these options.
+
+We use the "*build*" directory to keep object files and generated files
+away from the source tree.
+
+To run the configure script, change into the "*build*" directory, and
+run the "*configure*" script. Add any required options to the
+"`../configure`" command line::
+
+ cd build
+ ../configure
+
+Expect to see the "*configure*" script generate the following error::
+
+ /usr/bin/rm: cannot remove `libtoolT': No such file or directory
+
+This error is harmless and can be safely ignored.
+
+By default, libxo installs architecture-independent files, including
+extension library files, in the /usr/local directories. To specify an
+installation prefix other than /usr/local for all installation files,
+include the --prefix=prefix option and specify an alternate
+location. To install just the extension library files in a different,
+user-defined location, include the "*--with-extensions-dir=dir*" option
+and specify the location where the extension libraries will live::
+
+ cd build
+ ../configure [OPTION]... [VAR=VALUE]...
+
+Running the "make" Command
+++++++++++++++++++++++++++
+
+Once the "*configure*" script is run, build the images using the
+"`make`" command::
+
+ make
+
+Running the Regression Tests
+++++++++++++++++++++++++++++
+
+libxo includes a set of regression tests that can be run to ensure
+the software is working properly. These test are optional, but will
+help determine if there are any issues running libxo on your
+machine. To run the regression tests::
+
+ make test
+
+Installing libxo
+~~~~~~~~~~~~~~~~
+
+Once the software is built, you'll need to install libxo using the
+"`make install`" command. If you are the root user, or the owner of
+the installation directory, simply issue the command::
+
+ make install
+
+If you are not the "*root*" user and are using the "*sudo*" package, use::
+
+ sudo make install
+
+Verify the installation by viewing the output of "`xo --version`"::
+
+ % xo --version
+ libxo version 0.3.5-git-develop
+ xo version 0.3.5-git-develop
diff --git a/doc/howto.rst b/doc/howto.rst
new file mode 100644
index 000000000000..513572355bbc
--- /dev/null
+++ b/doc/howto.rst
@@ -0,0 +1,394 @@
+
+Howtos: Focused Directions
+==========================
+
+This section provides task-oriented instructions for selected tasks.
+If you have a task that needs instructions, please open a request as
+an enhancement issue on github.
+
+Howto: Report bugs
+------------------
+
+libxo uses github to track bugs or request enhancements. Please use
+the following URL:
+
+ https://github.com/Juniper/libxo/issues
+
+Howto: Install libxo
+--------------------
+
+libxo is open source, under a new BSD license. Source code is
+available on github, as are recent releases. To get the most
+current release, please visit:
+
+ https://github.com/Juniper/libxo/releases
+
+After downloading and untarring the source code, building involves the
+following steps::
+
+ sh bin/setup.sh
+ cd build
+ ../configure
+ make
+ make test
+ sudo make install
+
+libxo uses a distinct "*build*" directory to keep generated files
+separated from source files.
+
+.. index:: configure
+
+Use "`../configure --help`" to display available configuration
+options, which include the following::
+
+ --enable-warnings Turn on compiler warnings
+ --enable-debug Turn on debugging
+ --enable-text-only Turn on text-only rendering
+ --enable-printflike Enable use of GCC __printflike attribute
+ --disable-libxo-options Turn off support for LIBXO_OPTIONS
+ --with-gettext=PFX Specify location of gettext installation
+ --with-libslax-prefix=PFX Specify location of libslax config
+
+Compiler warnings are a very good thing, but recent compiler version
+have added some very pedantic checks. While every attempt is made to
+keep libxo code warning-free, warnings are now optional. If you are
+doing development work on libxo, it is required that you
+use --enable-warnings to keep the code warning free, but most users
+need not use this option.
+
+.. index:: --enable-text-only
+
+libxo provides the `--enable-text-only` option to reduce the
+footprint of the library for smaller installations. XML, JSON, and
+HTML rendering logic is removed.
+
+.. index:: --with-gettext
+
+The gettext library does not provide a simple means of learning its
+location, but libxo will look for it in /usr and /opt/local. If
+installed elsewhere, the installer will need to provide this
+information using the "`--with-gettext=/dir/path`" option.
+
+.. index:: libslax
+
+libslax is not required by libxo; it contains the "oxtradoc" program
+used to format documentation.
+
+For additional information, see :ref:`building`.
+
+Howto: Convert command line applications
+----------------------------------------
+
+Common question: How do I convert an existing command line application?
+
+There are four basic steps for converting command line application to
+use libxo::
+
+- Setting up the context
+- Converting printf calls
+- Creating hierarchy
+- Converting error functions
+
+Setting up the context
+~~~~~~~~~~~~~~~~~~~~~~
+
+To use libxo, you'll need to include the "xo.h" header file in your
+source code files::
+
+ #include
+
+In your main() function, you'll need to call xo_parse_args to handling
+argument parsing (:ref:`xo_parse_args`). This function removes
+libxo-specific arguments the program's argv and returns either the
+number of remaining arguments or -1 to indicate an error::
+
+ int
+ main (int argc, char **argv)
+ {
+ argc = xo_parse_args(argc, argv);
+ if (argc < 0)
+ return argc;
+ ....
+ }
+
+.. index:: atexit
+.. index:: xo_finish_atexit
+
+At the bottom of your main(), you'll need to call xo_finish() to
+complete output processing for the default handle (:ref:`handles`). This
+is required to flush internal information buffers. libxo provides the
+xo_finish_atexit function that is suitable for use with the
+:manpage:`atexit(3)` function::
+
+ atexit(xo_finish_atexit);
+
+Converting printf Calls
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The second task is inspecting code for :manpage:`printf(3)` calls and
+replacing them with xo_emit() calls. The format strings are similar
+in task, but libxo format strings wrap output fields in braces. The
+following two calls produce identical text output::
+
+ OLD::
+ printf("There are %d %s events\n", count, etype);
+
+ NEW::
+ xo_emit("There are {:count/%d} {:event} events\n", count, etype);
+
+"count" and "event" are used as names for JSON and XML output. The
+"count" field uses the format "%d" and "event" uses the default "%s"
+format. Both are "value" roles, which is the default role.
+
+Since text outside of output fields is passed verbatim, other roles
+are less important, but their proper use can help make output more
+useful. The "note" and "label" roles allow HTML output to recognize
+the relationship between text and the associated values, allowing
+appropriate "hover" and "onclick" behavior. Using the "units" role
+allows the presentation layer to perform conversions when needed. The
+"warning" and "error" roles allows use of color and font to draw
+attention to warnings. The "padding" role makes the use of vital
+whitespace more clear (:ref:`padding-role`).
+
+The "*title*" role indicates the headings of table and sections. This
+allows HTML output to use CSS to make this relationship more obvious::
+
+ OLD::
+ printf("Statistics:\n");
+
+ NEW::
+ xo_emit("{T:Statistics}:\n");
+
+The "*color*" roles controls foreground and background colors, as well
+as effects like bold and underline (see :ref:`color-role`)::
+
+ NEW::
+ xo_emit("{C:bold}required{C:}\n");
+
+Finally, the start- and stop-anchor roles allow justification and
+padding over multiple fields (see :ref:`anchor-role`)::
+
+ OLD::
+ snprintf(buf, sizeof(buf), "(%u/%u/%u)", min, ave, max);
+ printf("%30s", buf);
+
+ NEW::
+ xo_emit("{[:30}({:minimum/%u}/{:average/%u}/{:maximum/%u}{]:}",
+ min, ave, max);
+
+Creating Hierarchy
+~~~~~~~~~~~~~~~~~~
+
+Text output doesn't have any sort of hierarchy, but XML and JSON
+require this. Typically applications use indentation to represent
+these relationship::
+
+ OLD::
+ printf("table %d\n", tnum);
+ for (i = 0; i < tmax; i++) {
+ printf(" %s %d\n", table[i].name, table[i].size);
+ }
+
+ NEW::
+ xo_emit("{T:/table %d}\n", tnum);
+ xo_open_list("table");
+ for (i = 0; i < tmax; i++) {
+ xo_open_instance("table");
+ xo_emit("{P: }{k:name} {:size/%d}\n",
+ table[i].name, table[i].size);
+ xo_close_instance("table");
+ }
+ xo_close_list("table");
+
+The open and close list functions are used before and after the list,
+and the open and close instance functions are used before and after
+each instance with in the list.
+
+Typically these developer looks for a "for" loop as an indication of
+where to put these calls.
+
+In addition, the open and close container functions allow for
+organization levels of hierarchy::
+
+ OLD::
+ printf("Paging information:\n");
+ printf(" Free: %lu\n", free);
+ printf(" Active: %lu\n", active);
+ printf(" Inactive: %lu\n", inactive);
+
+ NEW::
+ xo_open_container("paging-information");
+ xo_emit("{P: }{L:Free: }{:free/%lu}\n", free);
+ xo_emit("{P: }{L:Active: }{:active/%lu}\n", active);
+ xo_emit("{P: }{L:Inactive: }{:inactive/%lu}\n", inactive);
+ xo_close_container("paging-information");
+
+Converting Error Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+libxo provides variants of the standard error and warning functions,
+:manpage:`err(3)` and :manpage:`warn(3)`. There are two variants, one
+for putting the errors on standard error, and the other writes the
+errors and warnings to the handle using the appropriate encoding
+style::
+
+ OLD::
+ err(1, "cannot open output file: %s", file);
+
+ NEW::
+ xo_err(1, "cannot open output file: %s", file);
+ xo_emit_err(1, "cannot open output file: {:filename}", file);
+
+.. index:: xo_finish
+
+Call xo_finish
+~~~~~~~~~~~~~~
+
+One important item: call `xo_finish` at the end of your program so
+ensure that all buffered data is written out. You can call it
+explicitly call it, or use :manpage:`atexit(3)` to have
+`xo_finish_atexit` called implicitly on exit::
+
+ OLD::
+ exit(0);
+
+ NEW::
+ xo_finish();
+ exit(0);
+
+Howto: Use "xo" in Shell Scripts
+--------------------------------
+
+.. admonition:: Needed
+
+ Documentation is needed for this area.
+
+.. index:: Internationalization (i18n)
+.. index:: gettext
+.. index:: xopo
+
+.. _i18n:
+
+Howto: Internationalization (i18n)
+-----------------------------------------------
+
+ How do I use libxo to support internationalization?
+
+libxo allows format and field strings to be used a keys into message
+catalogs to enable translation into a user's native language by
+invoking the standard :manpage:`gettext(3)` functions.
+
+gettext setup is a bit complicated: text strings are extracted from
+source files into "*portable object template*" (.pot) files using the
+`xgettext` command. For each language, this template file is used as
+the source for a message catalog in the "*portable object*" (.po)
+format, which are translated by hand and compiled into "*machine
+object*" (.mo) files using the `msgfmt` command. The .mo files are
+then typically installed in the /usr/share/locale or
+/opt/local/share/locale directories. At run time, the user's language
+settings are used to select a .mo file which is searched for matching
+messages. Text strings in the source code are used as keys to look up
+the native language strings in the .mo file.
+
+Since the xo_emit format string is used as the key into the message
+catalog, libxo removes unimportant field formatting and modifiers from
+the format string before use so that minor formatting changes will not
+impact the expensive translation process. We don't want a developer
+change such as changing "/%06d" to "/%08d" to force hand inspection of
+all .po files. The simplified version can be generated for a single
+message using the `xopo -s $text` command, or an entire .pot can be
+translated using the `xopo -f $input -o $output` command::
+
+ EXAMPLE:
+ % xopo -s "There are {:count/%u} {:event/%.6s} events\n"
+ There are {:count} {:event} events\n
+
+ Recommended workflow:
+ # Extract text messages
+ xgettext --default-domain=foo --no-wrap \
+ --add-comments --keyword=xo_emit --keyword=xo_emit_h \
+ --keyword=xo_emit_warn -C -E -n --foreign-user \
+ -o foo.pot.raw foo.c
+
+ # Simplify format strings for libxo
+ xopo -f foo.pot.raw -o foo.pot
+
+ # For a new language, just copy the file
+ cp foo.pot po/LC/my_lang/foo.po
+
+ # For an existing language:
+ msgmerge --no-wrap po/LC/my_lang/foo.po \
+ foo.pot -o po/LC/my_lang/foo.po.new
+
+ # Now the hard part: translate foo.po using tools
+ # like poedit or emacs' po-mode
+
+ # Compile the finished file; Use of msgfmt's "-v" option is
+ # strongly encouraged, so that "fuzzy" entries are reported.
+ msgfmt -v -o po/my_lang/LC_MESSAGES/foo.mo po/my_lang/foo.po
+
+ # Install the .mo file
+ sudo cp po/my_lang/LC_MESSAGES/foo.mo \
+ /opt/local/share/locale/my_lang/LC_MESSAGE/
+
+Once these steps are complete, you can use the `gettext` command to
+test the message catalog::
+
+ gettext -d foo -e "some text"
+
+i18n and xo_emit
+~~~~~~~~~~~~~~~~
+
+There are three features used in libxo used to support i18n:
+
+- The "{G:}" role looks for a translation of the format string.
+- The "{g:}" modifier looks for a translation of the field.
+- The "{p:}" modifier looks for a pluralized version of the field.
+
+Together these three flags allows a single function call to give
+native language support, as well as libxo's normal XML, JSON, and HTML
+support::
+
+ printf(gettext("Received %zu %s from {g:server} server\n"),
+ counter, ngettext("byte", "bytes", counter),
+ gettext("web"));
+
+ xo_emit("{G:}Received {:received/%zu} {Ngp:byte,bytes} "
+ "from {g:server} server\n", counter, "web");
+
+libxo will see the "{G:}" role and will first simplify the format
+string, removing field formats and modifiers::
+
+ "Received {:received} {N:byte,bytes} from {:server} server\n"
+
+libxo calls :manpage:`gettext(3)` with that string to get a localized
+version. If your language were *Pig Latin*, the result might look
+like::
+
+ "Eceivedray {:received} {N:byte,bytes} omfray "
+ "{:server} erversay\n"
+
+Note the field names do not change and they should not be translated.
+The contents of the note ("byte,bytes") should also not be translated,
+since the "g" modifier will need the untranslated value as the key for
+the message catalog.
+
+The field "{g:server}" requests the rendered value of the field be
+translated using :manpage:`gettext(3)`. In this example, "web" would
+be used.
+
+The field "{Ngp:byte,bytes}" shows an example of plural form using the
+"{p:}" modifier with the "{g:}" modifier. The base singular and plural
+forms appear inside the field, separated by a comma. At run time,
+libxo uses the previous field's numeric value to decide which form to
+use by calling :manpage:`ngettext(3)`.
+
+If a domain name is needed, it can be supplied as the content of the
+{G:} role. Domain names remain in use throughout the format string
+until cleared with another domain name::
+
+ printf(dgettext("dns", "Host %s not found: %d(%s)\n"),
+ name, errno, dgettext("strerror", strerror(errno)));
+
+ xo_emit("{G:dns}Host {:hostname} not found: "
+ "%d({G:strerror}{g:%m})\n", name, errno);
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 000000000000..2c889ceaa496
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,53 @@
+.. #
+ # Copyright (c) 2014, Juniper Networks, Inc.
+ # All rights reserved.
+ # This SOFTWARE is licensed under the LICENSE provided in the
+ # ../Copyright file. By downloading, installing, copying, or
+ # using the SOFTWARE, you agree to be bound by the terms of that
+ # LICENSE.
+ # Phil Shafer, July 2014
+ #
+
+.. default-role:: code
+
+libxo - A Library for Generating Text, XML, JSON, and HTML Output
+===================================================================
+
+The libxo library allows an application to generate text, XML, JSON,
+and HTML output, suitable for both command line use and for web
+applications. The application decides at run time which output style
+should be produced. By using libxo, a single source code path can
+emit multiple styles of output using command line options to select
+the style, along with optional behaviors. libxo includes support for
+multiple output streams, pluralization, color, syslog,
+:manpage:`humanized(3)` output, internationalization, and UTF-8. The
+library aims to minimize the cost of migrating code to libxo.
+
+libxo ships as part of FreeBSD.
+
+.. toctree::
+ :maxdepth: 3
+ :caption: Documentation Contents:
+
+ intro
+ getting
+ formatting
+ options
+ format-strings
+ field-roles
+ field-modifiers
+ field-formatting
+ api
+ xo
+ xolint
+ xohtml
+ xopo
+ faq
+ howto
+ example
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/doc/intro.rst b/doc/intro.rst
new file mode 100644
index 000000000000..40b3a4f4a5de
--- /dev/null
+++ b/doc/intro.rst
@@ -0,0 +1,90 @@
+
+Introducing libxo
+=================
+
+The libxo library allows an application to generate text, XML, JSON,
+and HTML output using a common set of function calls. The application
+decides at run time which output style should be produced. The
+application calls a function "xo_emit" to product output that is
+described in a format string. A "field descriptor" tells libxo what
+the field is and what it means. Each field descriptor is placed in
+braces with printf-like :ref:`format-strings`::
+
+ xo_emit(" {:lines/%7ju} {:words/%7ju} "
+ "{:characters/%7ju} {d:filename/%s}\n",
+ linect, wordct, charct, file);
+
+Each field can have a role, with the 'value' role being the default,
+and the role tells libxo how and when to render that field (see
+:ref:`field-roles` for details). Modifiers change how the field is
+rendered in different output styles (see :ref:`field-modifiers` for
+details. Output can then be generated in various style, using the
+"--libxo" option::
+
+ % wc /etc/motd
+ 25 165 1140 /etc/motd
+ % wc --libxo xml,pretty,warn /etc/motd
+
+
+ 25
+ 165
+ 1140
+ /etc/motd
+
+
+ % wc --libxo json,pretty,warn /etc/motd
+ {
+ "wc": {
+ "file": [
+ {
+ "lines": 25,
+ "words": 165,
+ "characters": 1140,
+ "filename": "/etc/motd"
+ }
+ ]
+ }
+ }
+ % wc --libxo html,pretty,warn /etc/motd
+
+
+
25
+
+
165
+
+
1140
+
+
/etc/motd
+
-
+
libxo: The Easy Way to Generate text, XML, JSON, and HTML output
libxo-manual
@@ -22676,13 +22676,13 @@ jQuery(function ($) {
#else
/* pooh */
#endif
-
But you'd really, really like all the fancy features that modern encoding formats can provide. libxo can help.
+
But you'd really, really like all the fancy features that modern encoding formats can provide. libxo can help.
The libxo library allows an application to generate text, XML, JSON, and HTML output using a common set of function calls. The application decides at run time which output style should be produced. The application calls a function "xo_emit" to product output that is described in a format string. A "field descriptor" tells libxo what the field is and what it means. Each field descriptor is placed in braces with a printf-like format string (Section 3.2):
xo_emit(" {:lines/%7ju} {:words/%7ju} "
"{:characters/%7ju} {d:filename/%s}\n",
linect, wordct, charct, file);
- Each field can have a role, with the 'value' role being the default, and the role tells libxo how and when to render that field (see Section 3.2.1 for details). Modifiers change how the field is rendered in different output styles (see Section 3.2.2 for details. Output can then be generated in various style, using the "‑‑libxo" option:
+
Each field can have a role, with the 'value' role being the default, and the role tells libxo how and when to render that field (see Section 3.2.1 for details). Modifiers change how the field is rendered in different output styles (see Section 3.2.2 for details. Output can then be generated in various style, using the "‑‑libxo" option:
% wc /etc/motd
25 165 1140 /etc/motd
@@ -22719,7 +22719,7 @@ jQuery(function ($) {
<div class="text"> </div>
<div class="data" data-tag="filename">/etc/motd</div>
</div>
- Same code path, same format strings, same information, but it's rendered in distinct styles based on run-time flags.
+
Same code path, same format strings, same information, but it's rendered in distinct styles based on run-time flags.
@@ -22736,7 +22736,7 @@ jQuery(function ($) {
We are following the branching scheme from http://nvie.com/posts/a-successful-git-branching-model/ which means we will do development under the "develop" branch, and release from the "master" branch. To clone a developer tree, run the following command:
git clone https://github.com/Juniper/libxo.git -b develop
-
We're using semantic release numbering, as defined in http://semver.org/spec/v2.0.0.html.
+
We're using semantic release numbering, as defined in http://semver.org/spec/v2.0.0.html.
libxo is open source, distributed under the BSD license. It shipped as part of the FreeBSD operating system starting with release 11.0.
Issues, problems, and bugs should be directly to the issues page on our github site.
Section Contents:
@@ -22756,12 +22756,12 @@ jQuery(function ($) {
tar -zxf libxo-RELEASE.tar.gz
cd libxo-RELEASE
- [Note: for Solaris users, your "tar" command lacks the "‑z" flag, so you'll need to substitute "gzip -dc "file" | tar xf -" instead of "tar -zxf "file"".]
+
[Note: for Solaris users, your "tar" command lacks the "‑z" flag, so you'll need to substitute "gzip -dc "file" | tar xf -" instead of "tar -zxf "file"".]
B) Use the current build from github. This gives you the most recent source code, which might be less stable than a specific release. To build libxo from the git repo:
git clone https://github.com/Juniper/libxo.git
cd libxo
- _BE AWARE_: The github repository does _not_ contain the files generated by "autoreconf", with the notable exception of the "m4" directory. Since these files (depcomp, configure, missing, install-sh, etc) are generated files, we keep them out of the source code repository.
+
_BE AWARE_: The github repository does _not_ contain the files generated by "autoreconf", with the notable exception of the "m4" directory. Since these files (depcomp, configure, missing, install-sh, etc) are generated files, we keep them out of the source code repository.
This means that if you download the a release distfile, these files will be ready and you'll just need to run "configure", but if you download the source code from svn, then you'll need to run "autoreconf" by hand. This step is done for you by the "setup.sh" script, described in the next section.
@@ -22779,7 +22779,7 @@ jQuery(function ($) {
make
make test
sudo make install
-
The following sections will walk through each of these steps with additional details and options, but the above directions should be all that's needed.
+
The following sections will walk through each of these steps with additional details and options, but the above directions should be all that's needed.
Section Contents:
- Section 2.2.1
@@ -22796,7 +22796,7 @@ jQuery(function ($) {
Run the "setup.sh" script to set up the build. This script runs the "autoreconf" command to generate the "configure" script and other generated files.
sh bin/setup.sh
- Note: We're are currently using autoreconf version 2.69.
+
Note: We're are currently using autoreconf version 2.69.
@@ -22810,15 +22810,15 @@ jQuery(function ($) {
cd build
../configure
- Expect to see the "configure" script generate the following error:
+
Expect to see the "configure" script generate the following error:
/usr/bin/rm: cannot remove `libtoolT': No such file or directory
- This error is harmless and can be safely ignored.
+
This error is harmless and can be safely ignored.
By default, libxo installs architecture-independent files, including extension library files, in the /usr/local directories. To specify an installation prefix other than /usr/local for all installation files, include the --prefix=prefix option and specify an alternate location. To install just the extension library files in a different, user-defined location, include the --with-extensions-dir=dir option and specify the location where the extension libraries will live.
cd build
../configure [OPTION]... [VAR=VALUE]...
- Section Contents:
+
Section Contents:
- Section 2.2.2.1
- Section 2.2.2.2
@@ -22832,7 +22832,7 @@ jQuery(function ($) {
Once the "configure" script is run, build the images using the "make" command:
make
-
+