1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
<section id="basic-interface">
<sectioninfo>
<title>Basic Interface</title>
<abstract><para>Using the basic interface</para></abstract>
</sectioninfo>
<section id="overview">
<title>Overview</title>
<para>The libfo basic interface defined in
<filename>fo-lifo-basic.h</filename> provides a high-level interface to the
formatter while hiding the use of GObjects.</para>
</section>
<section id="lifecycle">
<title>Lifecycle</title>
<para>The lifecycle is init–format–shutdown.</para>
<section id="initialize">
<title>Initialise</title>
<para>There are two ways to initialise the basic formatter. The first
way leaves memory allocation under the control of the formatter. The
second way allows the calling program to provide the functions to
be used for allocating, reallocating, and freeing memory.</para>
<programlisting>gboolean fo_libfo_init (void);
typedef gpointer (*FoMalloc) (gsize n_bytes);
typedef gpointer (*FoRealloc) (gpointer mem,
gsize n_bytes);
typedef void (*FoFree) (gpointer mem);
gboolean fo_libfo_init2 (FoMalloc fo_malloc,
FoRealloc fo_realloc,
FoFree fo_free);</programlisting>
<para>In both cases, the return value is an indication of whether or
not the formatter was successfully initialised. The functions return
<literal>TRUE</literal> on success, and <literal>FALSE</literal> on
failure.</para>
</section>
<section id="format">
<title>Format</title>
<para>There is one function for performing the formatting. The inputs
are:
</para>
<variablelist>
<varlistentry>
<term>libfo_context</term>
<listitem><para>Information controlling the formatting. See below.</para></listitem>
</varlistentry>
<varlistentry>
<term>xml</term>
<listitem><para>The filename of the input XML file.</para></listitem>
</varlistentry>
<varlistentry>
<term>xslt</term>
<listitem><para>The filename of the stylesheet file to apply.</para></listitem>
</varlistentry>
<varlistentry>
<term>out</term>
<listitem><para>The filename of the output PDF or PostScript file.</para></listitem>
</varlistentry>
<varlistentry>
<term>error</term>
<listitem><para>Indication of any error that occured.</para></listitem>
</varlistentry>
</variablelist>
<para>The return value is an indication of the success or failure of
the formatting. The function returns <literal>TRUE</literal> on
success, and <literal>FALSE</literal> on failure. When the return
value is <literal>FALSE</literal>, the <varname>error</varname> value
contains information about any error that occurred.</para>
<programlisting>gboolean fo_libfo_format (FoLibfoContext *libfo_context,
const gchar *xml,
const gchar *xslt,
const gchar *out,
GError **error);</programlisting>
</section>
<section id="shutdown">
<title>Shutdown</title>
<para>There is one function for shutting down the formatter.</para>
<programlisting>gboolean fo_libfo_shutdown (void);</programlisting>
<para>The return value is an indication of the success or failure of
the formatting. The function returns <literal>TRUE</literal> on
success, and <literal>FALSE</literal> on failure. However, if the
shutdown does fail, there isn't a whole lot that you can then
do.</para>
</section>
</section>
<section id="folibfocontext">
<title><classname>FoLibfoContext</classname></title>
<para>You can use a <classname>FoLibfoContext</classname> to control
aspects of the formatting, including:</para>
<itemizedlist>
<listitem><para>Output format (currently ignored).</para></listitem>
<listitem><para>Font embedding (currently ignored).</para></listitem>
<listitem><para>Validation of input XML document.</para></listitem>
<listitem><para>Use or non-use of SGML catalogs when parsing inputs.</para></listitem>
<listitem><para>Warning mode.</para></listitem>
<listitem><para>Debug mode.</para></listitem>
</itemizedlist>
</section>
</section>
|
