forked from podofo/podofo
-
Notifications
You must be signed in to change notification settings - Fork 0
/
FAQ.html
266 lines (230 loc) · 13 KB
/
FAQ.html
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
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>PoDoFo FAQ</title>
<style type="text/css">
h1 {
font-size: 140%;
}
h2 {
font-variant: small-caps;
font-size: 120%;
padding-left: 0.5em;
}
ul p {
font-variant: small-caps;
font-weight: bold;
}
.question {
font-style: italic;
padding-left: 1.5em;
font-size: 110%;
font-weight: bold;
}
.answer {
padding-left: 1.5em;
}
</style>
</head>
<body>
<h1>PoDoFo FAQ</h1>
<ul>
<p><a href="#s_general">General</a></p>
<ul>
<li><a href="#q_platforms">What platforms are supported by PoDoFo?</a></li>
<li><a href="#commercial">Can I use PoDoFo in my commercial application?</a></li>
<li><a href="#q_language">What language is PoDoFo written in?</a></li>
<li><a href="#q_stability">Does PoDoFo offer a stable API or ABI?</a></li>
<li><a href="#q_mailinglists">Does PoDoFo have a mailing list?</a></li>
<li><a href="#q_contact">My question isn't answered here. Where do I go next?</a></li>
</ul>
<p><a href="#s_otherlang">Other Programming Languages</a></p>
<ul>
<li><a href="#q_c">My program is written in C. Can I use PoDoFo?</a></li>
<li><a href="#q_cwrap">Is there a C wrapper for PoDoFo?</a></li>
<li><a href="#q_java">I'm a Java developer. Can I use PoDoFo?</a></li>
<li><a href="#q_otherlang">Are any other languages supported?</a></li>
</ul>
<p><a href="#s_troubleshooting">Troubleshooting</a></p>
<ul>
<li><a href="#q_stdterminate">Sometimes my program crashes in a call to PoDoFo
and produces a traceback including a call to
<code>std::terminate()</code>. Why?</a></li>
<li><a href="#q_sigabrt">Why does my program crash with a SIGABRT (Signal #6) in a call to PoDoFo?</a></li>
<li><a href="#q_setlocale">PoDoFo creates invalid PDF files because <b>,</b> is used in floats instead of <b>.</b> Why?</a></li>
</ul>
</ul>
<a name="s_general"><h2>General</h2></a>
<a name="q_platforms"><p class="question">What platforms are supported by PoDoFo?</p></a>
<p class="answer">PoDoFo has been tested on Linux, Mac OS X and
Windows. It is developed in a platform-independent way so that
porting to any other system should be no problem.</p>
<a name="q_commercial"><p class="question">Can I use PoDoFo in my commercial application?</p></a>
<div class="answer">
<p>Yes, though you must follow the terms of the LGPL license
for PoDoFo. The license permits you to use PoDoFo in any
commercial application, though the LGPL obliges you to provide
source to PoDoFo itself and any changes you made to it under
the LGPL. That means that you may link code to PoDoFo that is
not GPL- or LGPL-licensed so long as you follow the LGPL's
rules. You need not fear "viral code" here - not unless you
start copying chunks of PoDoFo into your own application, of
course. The inlining done by the compiler is considered
"linking" for the purposes of the license and thus not an
issue.</p>
<p>The PoDoFo developers would be happy if you would credit
them for using PoDoFo in your application, though this is not a
license obligation.</p>
</div>
<a name="q_language"><p class="question">What language is PoDoFo written in?</p></a>
<p class="answer">PoDoFo is written entirely in C++. If you're interested in using it from other languages, see the
<a href="#s_otherlang">section on those below</a>.</p>
<a name="q_stability"><p class="question">Does PoDoFo offer a stable API or ABI?</p></a>
<div class="answer">
<p>PoDoFo is not presently able to provider either a stable API
or ABI. The library is being developed quickly and still
requires a lot of changes to its interfaces as it is enhanced.</p>
<p>At present the best option for many users will be to target
a snapshot of PoDoFo or a particular release. An in-tree copy of
the library is not an unreasonable option, though care must be
taken to ensure that your copy doesn't end up as an increasingly
unmaintainable fork. The <a href="http://svnbook.red-bean.com/en/1.0/ch07s03.html">svn:externals</a> mechanism
is probably ideal for projects that use svn, since it lets you specify
a particular tag or revision that's versioned along with your project. See
PoDoFoBrowser for an example of this.</p>
<p>The README offers some more information on how to minimise the impact of
API changes on your application.</p>
<p>The PoDoFo developers are interested in offering a stable, maintained
release at some point, but the library is not yet at a point where that is
practical.</p>
</div>
<a name="q_mailinglists"><p class="question">Does PoDoFo have a mailing list?</p></a>
<p class="answer">Yes. See our <a href="http://podofo.sourceforge.net/support.html">support</a> pages. You're very welcome on the lists,
and they're not high-traffic. If you have a question, make sure to tell us your compiler and version, platform / OS and version, PoDoFo version,
where you got PoDoFo / how it was built, and the details of any error messages. If possible, upload a problem PDF document somewhere so that we can
get to it, too.</p>
<a name="q_contact"><p class="question">My question isn't answered here. Where do I go next?</p></a>
<p class="answer">Your best bet is to email the <a href="http://podofo.sourceforge.net/support.html">podofo-users mailing list</a>.</p>
<a name="s_otherlang"><h2>Other Programming Languages</h2></a>
<a name="q_c"><p class="question">My program is written in C. Can I use PoDoFo?</p></a>
<div class="answer">
<p>PoDoFo can not be used directly from a basic C program, but if you have access to a C++ compiler there are acceptable workarounds.</p>
<p>The cleanest approach is probably to write your PoDoFo-using
code as C++ and have it expose a pure C interface (using
<code>extern "C"</code> and the <code>nothrow()</code> qualifier) that can be used by
the rest of your program/library/plugin. With proper care and
attention to memory handling and exception safety in the code
that works directly with podofo, this approach should work
extremely well. You need to be careful not to allow exceptions
to unroll past your interface functions and into their pure-C
callers, and it's also necessary to be careful to use the C
library memory allocator when allocating memory that'll be
<code>free()</code>'d in your pure C code (or vice versa).</p>
<p>As an alternative, if your program compiles as C++ (most C
programs are legal C++), you may simply switch to building it
with a C++ compiler. You may then use PoDoFo directly, though
you'll still need to pay attention to cleaning up after an
exception is thrown to avoid leaking resources or leaving your
program in an invalid state. This is a reasonable approach for
stand-alone programs, but is unattractive for library authors,
plugin writers for C programs, and some other users.</p>
</div>
<a name="q_cwrap"><p class="question">Is there a C wrapper for PoDoFo?</p></a>
<div class="answer">
<p>Not as yet.</p>
<p>As PoDoFo does not make heavy use of templates in its general public API, it would be possible to write a fairly full-featured C wrapper around PoDoFo's public C++ APIs. Most of what'd be needed would be to:</p>
<ul>
<li>provide factory functions for PoDoFo objects</li>
<li>provide deletion functions for PoDoFo objects</li>
<li>write wrappers for methods that take an instance as
their first argument (also expanding overloaded
methods) and translate thrown exceptions into error
codes.</li>
</ul>
<p>The PoDoFo authors would be interested in hearing about any such effort, but are not working on anything along those lines themselves.</p>
</div>
<a name="q_java"><p class="question">I'm a Java developer. Can I use PoDoFo?</p></a>
<p class="answer">Not with Java, no, though we don't discriminate if
you've used it but want to move to another language ;-) . In all
seriousness a wrapper for Java may be possible, but nobody has been in
touch with the PoDoFo developers to express an interest in writing
one. Java users will probably want to look at <a href="http://itextpdf.com/">iText</a>.</p>
<a name="q_dotnet"><p class="question">I'm a C# or other .NET developer. Can I use PoDoFo?</p></a>
<p class="answer">Not easily. Since PoDoFo is unmanaged C++ code, you can use it with P/Invoke and a glue layer, but I wouldn't recommend
this as a pleasant way to use a library. If writing your PDF output code in C++ is an option, you may well be able to use PoDoFo.</p>
<a name="q_otherlang"><p class="question">Are any other languages supported?</p></a>
<p class="answer">No. Python bindings would be a fun <a href="http://www.boost.org/libs/python/doc/">Boost.Python</a> project, though.</p>
<a name="s_troubleshooting"><h2>Troubleshooting</h2></a>
<a name="q_stdterminate"><p class="question">Sometimes my program crashes in a call to PoDoFo
and produces a traceback including a call to
<code>std::terminate()</code>. Why?</p></a>
<div class="answer">
<p>If you're seeing a traceback including a call to <code>std::terminate()</code>,
like the (simplified) one shown below, the problem is probably that you're
not catching an exception being thrown by PoDoFo.</p>
<code>
raise()<br/>
abort()<br/>
std::set_unexpected()<br/>
<b>std::terminate</b>()<br/>
PoDoFo::SomePoDoFoMethod()<br/>
main()<br/>
</code>
<p>PoDoFo uses exceptions to indicate error conditions to the
caller, and your program is not handling an exception that is
thrown by PoDoFo. Your program should call all PoDoFo methods
that are not annotated `nothrow()' in a try/catch block, or be
prepared to handle the exception further up the call chain.
Code that calls PoDoFo should also be exception-safe.</p>
<p>In simplified terms, if you fail to catch an exception and
allow it to unroll the stack past your main() function, the
runtime will call <code>std::terminate()</code> for you. This
in turn will call <code>abort()</code>. On Linux, a
<code>SIGABRT</code> (Signal #6) will be generated and your
program will be terminated. Windows users may be informed that
their program has asked the runtime to terminate it in an
unusual way, or may get a crash dialog.</p>
</div>
<a name="q_sigabrt"><p class="question">Why does my program crash with a SIGABRT (Signal #6) in a call to PoDoFo?</p></a>
<p class="answer">You're probably not catching an exception being
thrown by PoDoFo. See the answer for std::terminate. Alternately, you
might be hitting an internal assertion in PoDoFo, indicating you've
found a library bug. If your problem isn't covered by the answer for
std::terminate, please report a bug and include the full PoDoFo library
version, a backtrace of the crash (this is critical), the code that
causes the crash if possible, the PDF document that causes the crash if
possible, and full information about your platform (OS/distro and
version, what the CPU is, etc).</p>
<a name="q_unusual_terminate"><p class="question">Why does my program exit with the message "Application has requested runtime to terminate it in an unusual way" ? </p>
<p class="answer">This is the Windows equivalent of a crash on a signal. This could easily be an error in your code, or an error from PoDoFo
crashing your program. You need to attach a debugger to find out. If you're using MinGW, install GDB from <a href="http://sourceforge.net/project/showfiles.php?group_id=2435">this page under "GNU Source Level Debugger"</a>, then run <code>gdb --args myprogram.exe</code>. Visual Studio users should use the integrated debugger. If the crash does appear to come from PoDoFo, make sure that you are correctly catching and handling exceptions thrown by PoDoFo - see the answer to <code>std::terminate</code>.</p>
<a name="q_setlocale"><p class="question">PoDoFo creates invalid PDF
files because <b>,</b> is used in floats instead of <b>.</b> Why?</p></a>
<p class="answer">PDF files use floating point numbers for almost all
drawing operations as coordinates. Those floating point numbers have to
be written in the English format with a <b>.</b> (point) as a separator.
Some languages like German use a <b>,</b> (comma) instead.<br/>
Earlier versions of PoDoFo used the current locale's C++ library formatting
operations to output values, causing these issues. Upgrade to a recent PoDoFo,
or run in the `C' locale.</p>
<a name="q_testsuites"><p class="question">Where can I get test PDF files?</p>
<p class="answer">
<ul>
<li>Misc. PDF test files
<ul>
<li><a href="http://www.novapdf.com/kb/pdf-example-files-created-with-novapdf-138.html">Example PDF files from novapdf.com</a>
They are for encryption, font subsetting and several other PDF features.
This link doesn't mean any recommendation.</li>
</ul>
</li>
<li>Colour and ICC:
<ul>
<li><a href="http://www.eci.org/doku.php?id=en:downloads#altona_test_suite">Altona test suite</a></li>
<li><a href="http://www.gwg.org/download/test-suites/ghent-output-suite/">Ghent Output Suite (version 4.0)</a></li>
</ul>
</li>
</ul>
</p>
</body>