source: pst/ps/fop.xml@ 498bc8e

10.0 10.1 11.0 9.1 ken/refactor-virt lazarus qt5new trunk upgradedb xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 498bc8e was 498bc8e, checked in by Bruce Dubbs <bdubbs@…>, 2 years ago

Update to fop-2.4.
Update to adwaita-icon-theme-3.34.3.

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

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