source: pst/ps/fop.xml@ 580fdfb

10.1 11.0 ken/refactor-virt lazarus qt5new trunk xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 580fdfb was 580fdfb, checked in by Bruce Dubbs <bdubbs@…>, 7 months ago

Misc tags

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@24282 af4574ff-66df-0310-9fd7-8a98e5e911e0

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