source: pst/ps/fop.xml

trunk
Last change on this file was 8558044, checked in by Pierre Labastie <pierre.labastie@…>, 3 months ago

Remove spaces at the end of lines

I know it is somewhat useless, but I don't like them for
two reasons: first they cannot be seen, and I do not like things I
cannot see. Second, git highlights them, and this is disturbing...

  • Property mode set to 100644
File size: 16.0 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY fop-download-http "https://archive.apache.org/dist/xmlgraphics/fop/source/fop-&fop-version;-src.tar.gz">
8 <!ENTITY fop-download-ftp " ">
9 <!ENTITY fop-md5sum "1d6bc84d2ab7f971bbc628080e3c307f">
10 <!ENTITY fop-size "26 MB">
11 <!ENTITY fop-buildsize "522 MB (including files downloaded to the user directory)">
12 <!ENTITY fop-time "0.4 SBU">
13
14 <!ENTITY pdfbox-version "2.0.24">
15 <!ENTITY pdfbox-download "http://archive.apache.org/dist/pdfbox/&pdfbox-version;/pdfbox-&pdfbox-version;.jar">
16 <!ENTITY pdfbox-md5sum "9e97fc59c662738a5fb82dcc447d1e2f">
17 <!ENTITY pdfbox-size "2.7 MB">
18
19 <!ENTITY fontbox-download "http://archive.apache.org/dist/pdfbox/&pdfbox-version;/fontbox-&pdfbox-version;.jar">
20 <!ENTITY fontbox-md5sum "6c2066df0d706d85e950fe8c73d52ed8">
21 <!ENTITY fontbox-size "1.5 MB">
22
23 <!ENTITY maven-major "3">
24 <!ENTITY maven-version "3.6.3">
25 <!ENTITY maven-download "http://archive.apache.org/dist/maven/maven-&maven-major;/&maven-version;/binaries/apache-maven-&maven-version;-bin.tar.gz">
26 <!ENTITY maven-md5sum "9792c717f5845d952907d5144b8253c3">
27 <!ENTITY maven-size "9.1 MB (additionally, about 82 MB are downloaded to the building user's directory)">
28
29 <!ENTITY offo-download "&sourceforge-dl;/offo/2.2/offo-hyphenation.zip">
30 <!ENTITY offo-md5sum "bf9c09bf05108ef9661b8f08d91c2336">
31 <!ENTITY offo-size "862 KB">
32]>
33
34<sect1 id="fop" xreflabel="fop-&fop-version;">
35 <?dbhtml filename="fop.html"?>
36
37 <sect1info>
38 <date>$Date$</date>
39 </sect1info>
40
41 <title>fop-&fop-version;</title>
42
43 <indexterm zone="fop">
44 <primary sortas="a-fop">fop</primary>
45 </indexterm>
46
47 <sect2 role="package">
48 <title>Introduction to fop</title>
49
50 <para>
51 The <application>FOP</application> (Formatting Objects Processor)
52 package contains a print formatter driven by XSL formatting objects
53 (XSL-FO). It is a <application>Java</application> application that reads
54 a formatting object tree and renders the resulting pages to a specified
55 output. Output formats currently supported include PDF, PCL, PostScript,
56 SVG, XML (area tree representation), print, AWT, MIF and ASCII text. The
57 primary output target is PDF.
58 </para>
59
60 &lfs110a_checked;
61
62 <bridgehead renderas="sect3">Package Information</bridgehead>
63 <itemizedlist spacing="compact">
64 <listitem>
65 <para>
66 Download (HTTP): <ulink url="&fop-download-http;"/>
67 </para>
68 </listitem>
69 <listitem>
70 <para>
71 Download (FTP): <ulink url="&fop-download-ftp;"/>
72 </para>
73 </listitem>
74 <listitem>
75 <para>
76 Download MD5 sum: &fop-md5sum;
77 </para>
78 </listitem>
79 <listitem>
80 <para>
81 Download size: &fop-size;
82 </para>
83 </listitem>
84 <listitem>
85 <para>
86 Estimated disk space required: &fop-buildsize;
87 </para>
88 </listitem>
89 <listitem>
90 <para>
91 Estimated build time: &fop-time;
92 </para>
93 </listitem>
94 </itemizedlist>
95
96 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
97 <itemizedlist spacing="compact">
98 <title>Required Additional Downloads:</title>
99 <listitem>
100 <para>
101 PDFBox:
102 <simplelist>
103 <member><ulink url="&pdfbox-download;"/></member>
104 <member>&pdfbox-md5sum;</member>
105 <member>&pdfbox-size;</member>
106 </simplelist>
107 </para>
108 </listitem>
109 <listitem>
110 <para>
111 PDFBox Fonts:
112 <simplelist>
113 <member><ulink url="&fontbox-download;"/></member>
114 <member>&fontbox-md5sum;</member>
115 <member>&fontbox-size;</member>
116 </simplelist>
117 </para>
118 </listitem>
119 <listitem>
120 <para>
121 Maven build system:
122 <simplelist>
123 <member><ulink url="&maven-download;"/></member>
124 <member>&maven-md5sum;</member>
125 <member>&maven-size;</member>
126 </simplelist>
127 </para>
128 </listitem>
129 </itemizedlist>
130<!-- Using the archive above allows finding all versions
131 <note><para>
132 The pdfbox and fontbox packages may not be available at the above
133 location. If not, they can be found at the BLFS files mirror sites.
134 </para></note>
135-->
136 <itemizedlist spacing="compact">
137 <title>Recommended packages</title>
138 <listitem>
139 <para>
140 Objects for Formatting Objects (OFFO) hyphenation patterns:
141 <simplelist>
142 <member><ulink url="&offo-download;"/></member>
143 <member>&offo-md5sum;</member>
144 <member>&offo-size;</member>
145 </simplelist>
146 </para>
147 </listitem>
148 </itemizedlist>
149
150 <bridgehead renderas="sect3">fop Dependencies</bridgehead>
151
152 <bridgehead renderas="sect4">Required</bridgehead>
153 <para role="required">
154 <xref linkend="apache-ant"/>
155 </para>
156
157 <bridgehead renderas="sect4">Optional</bridgehead>
158 <para role="optional">
159<!-- Included into ant <xref linkend="junit"/> (to run tests),-->
160 <xref linkend="x-window-system"/> (to run tests),
161<!-- <xref linkend="maven"/> (an alternate build system), not functional
162 with fop-2.3 -->
163 <ulink url="http://jai-tools.blogspot.com/">JAI Image I/O Tools</ulink>, and
164 <ulink url="http://jeuclid.sourceforge.net/">JEuclid</ulink>
165<!-- [pierre 2017-04-29] Note to devs: there are a lot of bundled dependencies.
166 Some were listed here, but not all. I am not sure it is possible to
167 use system ones. So, I have removed them, and kept only those which
168 are not bundled. -->
169 </para>
170
171 <para condition="html" role="usernotes">User Notes:
172 <ulink url="&blfs-wiki;/fop"/></para>
173
174 </sect2>
175
176 <sect2 role="installation">
177 <title>Installation of fop</title>
178
179 <para>
180 Ensure <envar>$JAVA_HOME</envar> is set correctly before beginning
181 the build. To build the <application>JIMI SDK</application> and/or
182 <application>XMLUnit</application> extension classes, ensure the
183 corresponding <filename class='extension'>.jar</filename> files can be
184 found via the <envar>CLASSPATH</envar> environment variable.
185 </para>
186
187 <sect3>
188 <title>Installing OFFO Hyphenation Patterns</title>
189
190 <para>
191 Copy the XML hyphenation patterns into the fop source tree by running
192 the following commands:
193 </para>
194
195<screen><userinput>unzip ../offo-hyphenation.zip &amp;&amp;
196cp offo-hyphenation/hyph/* fop/hyph &amp;&amp;
197rm -rf offo-hyphenation</userinput></screen>
198
199 </sect3>
200
201 <sect3>
202 <title>Installing a temporary Maven binary</title>
203
204 <para>
205 Starting with fop-2.5, the Maven build system is required. We use
206 the binary provided by apache, that we install in a temporary location:
207 </para>
208
209<screen><userinput>tar -xf ../apache-maven-&maven-version;-bin.tar.gz -C /tmp</userinput></screen>
210
211 </sect3>
212
213 <sect3>
214 <title>Installing fop Components</title>
215
216 <para>
217 The <command>javadoc</command> command that ships with OpenJDK 10 and
218 later has
219 become much stricter than previous versions regarding conformance of
220 the Javadoc comments in source code to HTML. The FOP documentation does
221 not meet those standards, so the conformance checks have to be
222 disabled. This can be done with the following command:
223 </para>
224
225<screen><userinput>sed -i '\@&lt;/javad@i\
226&lt;arg value="-Xdoclint:none"/&gt;\
227&lt;arg value="--allow-script-in-comments"/&gt;\
228&lt;arg value="--ignore-source-errors"/&gt;' \
229 fop/build.xml</userinput></screen>
230<!-- Seems to have been fixed in 2.6
231 <para>
232 The stack size set in <filename>build.xml</filename> for building the
233 hyphenation patterns is not large enough. Change it by running:
234 </para>
235
236<screen><userinput>sed -e '/hyph\.stack/s/512k/1M/' \
237 -i fop/build.xml</userinput></screen>
238-->
239 <para>
240 Fix building with JDK-16 due to an outdated Apache Maven plugin:
241 </para>
242
243<screen><userinput remap="pre">sed -i 's/&lt;war.plugin.version&gt;2.2/&lt;war.plugin.version&gt;3.3.1/' pom.xml</userinput></screen>
244
245 <para>
246 The <filename>build.xml</filename> file calls for an old version of
247 <application>PDFBox</application> components that are no longer
248 available. Copy the updated PDFBox components into the source tree:
249 </para>
250
251<screen><userinput>cp ../{pdf,font}box-&pdfbox-version;.jar fop/lib</userinput></screen>
252
253 <para>
254 Compile <application>fop</application> by running the following
255 commands:
256 </para>
257
258<screen><userinput>cd fop &amp;&amp;
259
260LC_ALL=en_US.UTF-8 \
261PATH=$PATH:/tmp/apache-maven-&maven-version;/bin \
262ant all javadocs &amp;&amp;
263
264mv build/javadocs .</userinput></screen>
265
266 <para>
267 This package comes with a testsuite, but the java infrastructure
268 installed in this book does not allow running it.
269 </para>
270
271 <para>
272 Now, install <application>Fop</application> as the
273 <systemitem class="username">root</systemitem> user:
274 </para>
275
276<screen role="root"><userinput>install -v -d -m755 -o root -g root /opt/fop-&fop-version; &amp;&amp;
277cp -vR build conf examples fop* javadocs lib /opt/fop-&fop-version; &amp;&amp;
278chmod a+x /opt/fop-&fop-version;/fop &amp;&amp;
279ln -v -sfn fop-&fop-version; /opt/fop</userinput></screen>
280
281 <para>
282 The last thing to do is to clean what we have done:
283 </para>
284
285<screen><userinput>rm -rf /tmp/apache-maven-&maven-version;</userinput></screen>
286
287 </sect3>
288
289 </sect2>
290
291 <sect2 role="commands">
292 <title>Command Explanations</title>
293
294 <para>
295 <command>sed -i ... build.xml</command>: This adds two switches to the
296 <command>javadoc</command> command, preventing some errors from occuring
297 when building the documentation.
298 </para>
299
300 <para>
301 <command>export LC_ALL=en_US.UTF-8</command>: the compiler fails if using
302 an ASCII locale.
303 </para>
304
305 <para>
306 <command>ant <option>target</option></command>: This reads the file
307 <filename>build.xml</filename> and builds the target: <option>compile
308 </option> compiles the java sources, <option>jar-main</option> generates
309 jar archives, <option>jar-hyphenation</option> generates the hyphenation
310 patterns for FOP, <option>junit</option> runs the
311 <application>junit</application> tests, and <option>javadocs</option>
312 builds the documentation. The <option>all</option> target runs all of the
313 above.
314 </para>
315
316 <para>
317 <command>ln -v -sf fop-&fop-version; /opt/fop</command>: This is
318 optional and creates a convenience symlink so that
319 <envar>$FOP_HOME</envar> doesn't have to be changed each time there's a
320 package version change.
321 </para>
322
323 </sect2>
324
325 <sect2 role="configuration">
326 <title>Configuring fop</title>
327
328 <sect3 id="fop-config">
329 <title>Config Files</title>
330
331 <para>
332 <filename>~/.foprc</filename>
333 </para>
334
335 <indexterm zone="fop fop-config">
336 <primary sortas="e-AA.foprc">~/.foprc</primary>
337 </indexterm>
338
339 </sect3>
340
341 <sect3>
342 <title>Configuration Information</title>
343
344 <para>
345 Using <application>fop</application> to process some large FO's
346 (including the FO derived from the BLFS XML sources), can lead to
347 memory errors. Unless you add a parameter to the
348 <command>java</command> command used in the <command>fop</command>
349 script you may receive messages similar to the one shown below:
350 </para>
351
352 <para>
353 <computeroutput>
354 Exception in thread "main" java.lang.OutOfMemoryError: Java heap
355 space
356 </computeroutput>
357 </para>
358
359 <para>
360 To avoid errors like this, you need to pass an extra parameter to
361 the <command>java</command> command used in the <command>fop</command>
362 script. This can be accomplished by creating a
363 <filename>~/.foprc</filename> (which is sourced by the
364 <command>fop</command> script) and adding the parameter to the
365 <envar>FOP_OPTS</envar> environment variable.
366 </para>
367
368 <para>
369 The <command>fop</command> script looks for a
370 <envar>FOP_HOME</envar> environment variable to locate the
371 <application>fop</application> class libraries. You can create this
372 variable using the <filename>~/.foprc</filename> file as well. Create
373 a <filename>~/.foprc</filename> file using the following commands:
374 </para>
375
376<screen><userinput>cat &gt; ~/.foprc &lt;&lt; "EOF"
377<literal>FOP_OPTS="-Xmx<replaceable>&lt;RAM_Installed&gt;</replaceable>m"
378FOP_HOME="/opt/fop"</literal>
379EOF</userinput></screen>
380
381 <para>
382 Replace <replaceable>&lt;RAM_Installed&gt;</replaceable> with a
383 number representing the amount of RAM installed in your computer (in
384 megabytes). An example would be
385 <userinput>FOP_OPTS="-Xmx768m"</userinput>.
386 <!-- the URL is broken
387 For more information about
388 memory issues running <application>fop</application>, see
389 <ulink url="http://xml.apache.org/fop/running.html#memory"/>.
390 -->
391 </para>
392
393 <para>
394 To include the <command>fop</command> script in your path,
395 update the system-wide profile with the following command as the
396 <systemitem class="username">root</systemitem> user:
397 </para>
398
399<screen role="root"><userinput>cat &gt; /etc/profile.d/fop.sh &lt;&lt; "EOF"
400<literal># Begin /etc/profile.d/fop.sh
401
402pathappend /opt/fop
403
404# End /etc/profile.d/fop.sh</literal>
405EOF</userinput></screen>
406
407 <note>
408 <para>
409 Running <command>fop</command> can be somewhat verbose.
410 The default logging level can be changed from INFO to any of
411 FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, ALL, or OFF.
412 To do this, edit
413 <filename>$JAVA_HOME/jre/lib/logging.properties</filename> and change
414 the entries for <option>.level</option> and
415 <option>java.util.logging.ConsoleHandler.level</option> to
416 the desired value.
417 </para>
418 </note>
419
420 </sect3>
421
422 </sect2>
423
424 <sect2 role="content">
425 <title>Contents</title>
426
427 <segmentedlist>
428 <segtitle>Installed Programs</segtitle>
429 <segtitle>Installed Libraries</segtitle>
430 <segtitle>Installed Directory</segtitle>
431
432 <seglistitem>
433 <seg>fop</seg>
434 <seg>fop.jar and numerous support library classes located in
435 <filename class="directory">/opt/fop/{build,lib}</filename>; JAI
436 components include libmlib_jai.so, jai_codec.jar, jai_core.jar, and
437 mlibwrapper_jai.jar</seg>
438 <seg>/opt/fop-&fop-version;</seg>
439 </seglistitem>
440 </segmentedlist>
441
442 <variablelist>
443 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
444 <?dbfo list-presentation="list"?>
445 <?dbhtml list-presentation="table"?>
446
447 <varlistentry id="fop-prog">
448 <term><command>fop</command></term>
449 <listitem>
450 <para>
451 is a wrapper script to the <command>java</command> command
452 which sets up the <application>fop</application>
453 environment and passes the required parameters
454 </para>
455 <indexterm zone="fop fop-prog">
456 <primary sortas="b-fop">fop</primary>
457 </indexterm>
458 </listitem>
459 </varlistentry>
460
461 <varlistentry id="fop.jar">
462 <term><filename class="libraryfile">fop.jar</filename></term>
463 <listitem>
464 <para>
465 contains all the <application>fop</application>
466 <application>Java</application> classes
467 </para>
468 <indexterm zone="fop fop.jar">
469 <primary sortas="c-fop.jar">fop.jar</primary>
470 </indexterm>
471 </listitem>
472 </varlistentry>
473
474 </variablelist>
475
476 </sect2>
477
478</sect1>
Note: See TracBrowser for help on using the repository browser.