contrib/libxo/libxo/xo_set_info.3

   1 .\" #
   2 .\" # Copyright (c) 2014, Juniper Networks, Inc.
   3 .\" # All rights reserved.
   4 .\" # This SOFTWARE is licensed under the LICENSE provided in the
   5 .\" # ../Copyright file. By downloading, installing, copying, or
   6 .\" # using the SOFTWARE, you agree to be bound by the terms of that
   7 .\" # LICENSE.
   8 .\" # Phil Shafer, July 2014
   9 .\"
  10 .Dd July, 2014
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm xo_emit
  15 .Nd emit formatted output based on format string and arguments
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Ft void
  21 .Fn xo_set_info "xo_handle_t *handle" "xo_info_t *info" "int count"
  22 .Sh DESCRIPTION
  23 HTML data can include additional information in attributes that
  24 begin with "data-".  To enable this, three things must occur:
  25 .Pp
  26 First the application must build an array of xo_info_t structures,
  27 one per tag.  The array must be sorted by name, since
  28 .Em libxo
  29 uses a
  30 binary search to find the entry that matches names from format
  31 instructions.
  32 .Pp
  33 The
  34 .Em xo_info_t
  35 structure is defined in
  36 .Em <libxo/xo.h> :
  37 .Bd -literal -offset indent
  38     typedef struct xo_info_s {
  39         const char *xi_name;    /* Name of the element */
  40         const char *xi_type;    /* Type of field */
  41         const char *xi_help;    /* Description of field */
  42     } xo_info_t;
  43 .Ed
  44 .Pp
  45 Second, the application must inform
  46 .Em libxo
  47 about this information using the
  48 .Fn xo_set_info
  49 call.  Like other libxo calls, passing NULL for the handle tells
  50 .Em libxo
  51 to use the default handle.
  52 .Pp
  53 If the
  54 .Fa count
  55 is -1,
  56 .Em libxo
  57 will count the elements of
  58 .Fa info ,
  59 but there
  60 must be an empty element at the end.  More typically, the number is
  61 known to the application:
  62 .Bd -literal -offset indent
  63     xo_info_t info[] = {
  64         { "in-stock", "number", "Number of items in stock" },
  65         { "name", "string", "Name of the item" },
  66         { "on-order", "number", "Number of items on order" },
  67         { "sku", "string", "Stock Keeping Unit" },
  68         { "sold", "number", "Number of items sold" },
  69     };
  70     int info_count = (sizeof(info) / sizeof(info[0]));
  71     ...
  72     xo_set_info(NULL, info, info_count);
  73 .Ed
  74 .Pp
  75 Third, the emitting of info must be triggered with the
  76 .Em XOF_INFO
  77 flag
  78 using either the
  79 .Fn xo_set_flags
  80 function or the
  81 .Dq --libxo=info
  82 command line argument.
  83 .Pp
  84 The type and help values, if present, are emitted as the "data-type"
  85 and "data-help" attributes:
  86 .Bd -literal -offset indent
  87   <div class="data" data-tag="sku" data-type="string"
  88        data-help="Stock Keeping Unit">GRO-000-533</div>
  89 .Ed
  90 .Sh ADDITIONAL DOCUMENTATION
  91 .Pp
  92 Complete documentation can be found on github:
  93 .Bd -literal -offset indent
  94 http://juniper.github.io/libxo/libxo-manual.html
  95 .Ed
  96 .Pp
  97 libxo lives on github as:
  98 .Bd -literal -offset indent
  99 https://github.com/Juniper/libxo
 100 .Ed
 101 .Pp
 102 The latest release of libxo is available at:
 103 .Bd -literal -offset indent
 104 https://github.com/Juniper/libxo/releases
 105 .Ed
 106 .Sh SEE ALSO
 107 .Xr xo_emit 3
 108 .Sh HISTORY
 109 The
 110 .Fa libxo
 111 library was added in FreeBSD 11.0.
 112 .Sh AUTHOR
 113 Phil Shafer