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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Basic Interface</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
<meta name="description" content="Using the basic interface">
<link rel="start" href="index.html" title="xmlroff Reference Manual">
<link rel="up" href="developers.html" title="Developers' Guide">
<link rel="prev" href="debugging.html" title="Debugging xmlroff">
<link rel="next" href="backends.html" title="FoDoc and xmlroff Backends">
<meta name="generator" content="GTK-Doc V1.10 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="chapter" href="users.html" title="Users' Guide">
<link rel="chapter" href="developers.html" title="Developers' Guide">
<link rel="chapter" href="object-hierarchy.html" title="Object Hierarchy">
<link rel="chapter" href="object.html" title="FoObject is wonderful">
<link rel="chapter" href="node.html" title="FoNode is wonderful">
<link rel="chapter" href="interfaces.html" title="Interfaces are truly wonderful">
<link rel="chapter" href="formatting-objects.html" title="Formatting Objects are truly wonderful">
<link rel="chapter" href="properties.html" title="Properties">
<link rel="chapter" href="areas.html" title="Area Objects">
<link rel="chapter" href="datatypes.html" title="Datatype Objects">
<link rel="chapter" href="context.html" title="Property Context Object">
<link rel="chapter" href="other-objects.html" title="Other Objects">
<link rel="chapter" href="utility-objects.html" title="Utility Objects">
<link rel="chapter" href="utility-modules.html" title="Utility Modules">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="debugging.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="developers.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">xmlroff Reference Manual</th>
<td><a accesskey="n" href="backends.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="section" lang="en">
<div class="titlepage"><div>
<div><h2 class="title" style="clear: both">
<a name="basic-interface"></a>Basic Interface</h2></div>
<div><div class="abstract">
<p class="title"><b>Abstract</b></p>
<p>Using the basic interface</p>
</div></div>
</div></div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="overview"></a>Overview</h3></div></div></div>
<p>The libfo basic interface defined in
<code class="filename">fo-lifo-basic.h</code> provides a high-level interface to the
formatter while hiding the use of GObjects.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="lifecycle"></a>Lifecycle</h3></div></div></div>
<p>The lifecycle is init–format–shutdown.</p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="initialize"></a>Initialise</h4></div></div></div>
<p>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.</p>
<pre class="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);</pre>
<p>In both cases, the return value is an indication of whether or
not the formatter was successfully initialised. The functions return
<code class="literal">TRUE</code> on success, and <code class="literal">FALSE</code> on
failure.</p>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="format"></a>Format</h4></div></div></div>
<p>There is one function for performing the formatting. The inputs
are:
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term">libfo_context</span></p></td>
<td><p>Information controlling the formatting. See below.</p></td>
</tr>
<tr>
<td><p><span class="term">xml</span></p></td>
<td><p>The filename of the input XML file.</p></td>
</tr>
<tr>
<td><p><span class="term">xslt</span></p></td>
<td><p>The filename of the stylesheet file to apply.</p></td>
</tr>
<tr>
<td><p><span class="term">out</span></p></td>
<td><p>The filename of the output PDF or PostScript file.</p></td>
</tr>
<tr>
<td><p><span class="term">error</span></p></td>
<td><p>Indication of any error that occured.</p></td>
</tr>
</tbody>
</table></div>
<p>The return value is an indication of the success or failure of
the formatting. The function returns <code class="literal">TRUE</code> on
success, and <code class="literal">FALSE</code> on failure. When the return
value is <code class="literal">FALSE</code>, the <code class="varname">error</code> value
contains information about any error that occurred.</p>
<pre class="programlisting">gboolean fo_libfo_format (FoLibfoContext *libfo_context,
const gchar *xml,
const gchar *xslt,
const gchar *out,
GError **error);</pre>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="shutdown"></a>Shutdown</h4></div></div></div>
<p>There is one function for shutting down the formatter.</p>
<pre class="programlisting">gboolean fo_libfo_shutdown (void);</pre>
<p>The return value is an indication of the success or failure of
the formatting. The function returns <code class="literal">TRUE</code> on
success, and <code class="literal">FALSE</code> on failure. However, if the
shutdown does fail, there isn't a whole lot that you can then
do.</p>
</div>
</div>
<div class="section" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="folibfocontext"></a><code class="classname">FoLibfoContext</code>
</h3></div></div></div>
<p>You can use a <code class="classname">FoLibfoContext</code> to control
aspects of the formatting, including:</p>
<div class="itemizedlist"><ul type="disc">
<li><p>Output format (currently ignored).</p></li>
<li><p>Font embedding (currently ignored).</p></li>
<li><p>Validation of input XML document.</p></li>
<li><p>Use or non-use of SGML catalogs when parsing inputs.</p></li>
<li><p>Warning mode.</p></li>
<li><p>Debug mode.</p></li>
</ul></div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.10</div>
</body>
</html>
|
