103 lines
2.5 KiB
Groff
103 lines
2.5 KiB
Groff
.\" #
|
|
.\" # 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
|
|
.\"
|
|
.Dd December 4, 2014
|
|
.Dt LIBXO 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm xo_set_info
|
|
.Nd set the field information data for libxo
|
|
.Sh LIBRARY
|
|
.Lb libxo
|
|
.Sh SYNOPSIS
|
|
.In libxo/xo.h
|
|
.Ft void
|
|
.Fn xo_set_info "xo_handle_t *handle" "xo_info_t *info" "int count"
|
|
.Sh DESCRIPTION
|
|
HTML data can include additional information in attributes that
|
|
begin with "data-".
|
|
To enable this, three things must occur:
|
|
.Pp
|
|
First the application must build an array of
|
|
.Dv xo_info_t
|
|
structures,
|
|
one per tag.
|
|
The array must be sorted by name, since
|
|
.Nm libxo
|
|
uses a
|
|
binary search to find the entry that matches names from format
|
|
instructions.
|
|
.Pp
|
|
The
|
|
.Dv xo_info_t
|
|
structure is defined in
|
|
.In libxo/xo.h :
|
|
.Bd -literal -offset indent
|
|
typedef struct xo_info_s {
|
|
const char *xi_name; /* Name of the element */
|
|
const char *xi_type; /* Type of field */
|
|
const char *xi_help; /* Description of field */
|
|
} xo_info_t;
|
|
.Ed
|
|
.Pp
|
|
Second, the application must inform
|
|
.Nm libxo
|
|
about this information using the
|
|
.Fn xo_set_info
|
|
call.
|
|
Like other
|
|
.Nm libxo
|
|
calls, passing
|
|
.Dv NULL
|
|
for the handle tells
|
|
.Nm libxo
|
|
to use the default handle.
|
|
.Pp
|
|
If the
|
|
.Fa count
|
|
is -1,
|
|
.Nm libxo
|
|
will count the elements of
|
|
.Fa info ,
|
|
but there
|
|
must be an empty element at the end.
|
|
More typically, the number is
|
|
known to the application:
|
|
.Bd -literal -offset indent
|
|
xo_info_t info[] = {
|
|
{ "in-stock", "number", "Number of items in stock" },
|
|
{ "name", "string", "Name of the item" },
|
|
{ "on-order", "number", "Number of items on order" },
|
|
{ "sku", "string", "Stock Keeping Unit" },
|
|
{ "sold", "number", "Number of items sold" },
|
|
};
|
|
int info_count = (sizeof(info) / sizeof(info[0]));
|
|
...
|
|
xo_set_info(NULL, info, info_count);
|
|
.Ed
|
|
.Pp
|
|
Third, the emission of info must be triggered with the
|
|
.Dv XOF_INFO
|
|
flag
|
|
using either the
|
|
.Fn xo_set_flags
|
|
function or the
|
|
.Dq --libxo=info
|
|
command line argument.
|
|
.Pp
|
|
The type and help values, if present, are emitted as the "data-type"
|
|
and "data-help" attributes:
|
|
.Bd -literal -offset indent
|
|
<div class="data" data-tag="sku" data-type="string"
|
|
data-help="Stock Keeping Unit">GRO-000-533</div>
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr xo_emit 3 ,
|
|
.Xr libxo 3
|