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 December 4, 2014
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm xo_set_info
  15 .Nd set the field information data for libxo
  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-".
  25 To enable this, three things must occur:
  26 .Pp
  27 First the application must build an array of
  28 .Dv xo_info_t
  29 structures,
  30 one per tag.
  31 The array must be sorted by name, since
  32 .Nm libxo
  33 uses a
  34 binary search to find the entry that matches names from format
  35 instructions.
  36 .Pp
  37 The
  38 .Dv xo_info_t
  39 structure is defined in
  40 .In libxo/xo.h :
  41 .Bd -literal -offset indent
  42     typedef struct xo_info_s {
  43         const char *xi_name;    /* Name of the element */
  44         const char *xi_type;    /* Type of field */
  45         const char *xi_help;    /* Description of field */
  46     } xo_info_t;
  47 .Ed
  48 .Pp
  49 Second, the application must inform
  50 .Nm libxo
  51 about this information using the
  52 .Fn xo_set_info
  53 call.
  54 Like other
  55 .Nm libxo
  56 calls, passing
  57 .Dv NULL
  58 for the handle tells
  59 .Nm libxo
  60 to use the default handle.
  61 .Pp
  62 If the
  63 .Fa count
  64 is -1,
  65 .Nm libxo
  66 will count the elements of
  67 .Fa info ,
  68 but there
  69 must be an empty element at the end.
  70 More typically, the number is
  71 known to the application:
  72 .Bd -literal -offset indent
  73     xo_info_t info[] = {
  74         { "in-stock", "number", "Number of items in stock" },
  75         { "name", "string", "Name of the item" },
  76         { "on-order", "number", "Number of items on order" },
  77         { "sku", "string", "Stock Keeping Unit" },
  78         { "sold", "number", "Number of items sold" },
  79     };
  80     int info_count = (sizeof(info) / sizeof(info[0]));
  81     ...
  82     xo_set_info(NULL, info, info_count);
  83 .Ed
  84 .Pp
  85 Third, the emission of info must be triggered with the
  86 .Dv XOF_INFO
  87 flag
  88 using either the
  89 .Fn xo_set_flags
  90 function or the
  91 .Dq --libxo=info
  92 command line argument.
  93 .Pp
  94 The type and help values, if present, are emitted as the "data-type"
  95 and "data-help" attributes:
  96 .Bd -literal -offset indent
  97   <div class="data" data-tag="sku" data-type="string"
  98        data-help="Stock Keeping Unit">GRO-000-533</div>
  99 .Ed
 100 .Sh SEE ALSO
 101 .Xr xo_emit 3 ,
 102 .Xr libxo 3
 103 .Sh HISTORY
 104 The
 105 .Nm libxo
 106 library first appeared in
 107 .Fx 11.0 .
 108 .Sh AUTHORS
 109 .Nm libxo
 110 was written by
 111 .An Phil Shafer Aq Mt phil@freebsd.org .
 112