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);