source: pst/ps/fop.xml@ d61ead0a

10.0 10.1 11.0 11.1 11.2 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind lazarus perl-modules plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since d61ead0a was d61ead0a, checked in by DJ Lucas <dj@…>, 5 years ago

Update to OpenJDK-9.0.4.
Update to make-ca-0.7.
Update to Apache-Ant-1.10.2.

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

  • Property mode set to 100644
File size: 13.5 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 "6d2388bd8851b4883d3258c0afc96895">
10 <!ENTITY fop-size "24 MB">
11 <!ENTITY fop-buildsize "493 MB (add 39 MB for tests)">
12 <!ENTITY fop-time "0.7 SBU (add 0.7 SBU for tests)">
13
14 <!ENTITY jai-version "1_1_3">
15 <!ENTITY jai-download "http://download.java.net/media/jai/builds/release/&jai-version;/jai-&jai-version;-lib-linux-i586.tar.gz">
16 <!ENTITY jai-md5sum "a2cbc155ef3899bcde9c74a8035764b3">
17 <!ENTITY jai-size "3.4 MB">
18
19 <!ENTITY jai64-download "http://download.java.net/media/jai/builds/release/&jai-version;/jai-&jai-version;-lib-linux-amd64.tar.gz">
20 <!ENTITY jai64-md5sum "4a906db35612f668aeef2c0606d7075b">
21 <!ENTITY jai64-size "3.4 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 &lfs81_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>Recommended packages</title>
82
83 <listitem>
84 <para>Objects for Formatting Objects (OFFO) hyphenation patterns:
85 <simplelist>
86 <member><ulink url="&offo-download;"/></member>
87 <member>&offo-md5sum;</member>
88 <member>&offo-size;</member>
89 </simplelist>
90 </para>
91 </listitem>
92 </itemizedlist>
93
94 <bridgehead renderas="sect3">fop Dependencies</bridgehead>
95
96 <bridgehead renderas="sect4">Required</bridgehead>
97 <para role="required">
98 <xref linkend="apache-ant"/>
99 </para>
100
101 <bridgehead renderas="sect4">Optional</bridgehead>
102 <para role="optional">
103 <xref linkend="junit"/> (to run tests),
104 <xref linkend="x-window-system"/> (to run tests),
105 <ulink url="https://maven.apache.org/">Maven</ulink>,
106 <ulink url="https://java.net/projects/jai-imageio">JAI Image I/O Tools</ulink>, and
107 <ulink url="http://jeuclid.sourceforge.net/">JEuclid</ulink>
108<!-- [pierre 2017-04-29] Note to devs: there are a lot of bundled dependencies.
109 Some were listed here, but not all. I am not sure it is possible to
110 use system ones. So, I have removed them, an kept only those which
111 are not bundled. -->
112 </para>
113
114 <para condition="html" role="usernotes">User Notes:
115 <ulink url="&blfs-wiki;/fop"/></para>
116
117 </sect2>
118
119 <sect2 role="installation">
120 <title>Installation of fop</title>
121
122 <para>
123 Ensure <envar>$JAVA_HOME</envar> is set correctly before beginning
124 the build. To build the <application>JIMI SDK</application> and/or
125 <application>XMLUnit</application> extension classes, ensure the
126 corresponding <filename class='extension'>.jar</filename> files can be
127 found via the <envar>CLASSPATH</envar> environment variable.
128 </para>
129
130 <sect3>
131 <title>Installing OFFO Hyphenation Patterns</title>
132
133 <para>
134 Copy the XML hyphenation patterns into the fop source tree by running
135 the following commands:
136 </para>
137
138<screen><userinput>unzip ../offo-hyphenation.zip &amp;&amp;
139cp offo-hyphenation/hyph/* fop/hyph &amp;&amp;
140rm -rf offo-hyphenation</userinput></screen>
141
142 </sect3>
143
144 <sect3>
145 <title>Installing fop Components</title>
146
147 <para>
148 The <command>javadoc</command> command coming with OpenJDK 9 has
149 become much stricter than before regarding the conformance of the
150 Javadoc comments in source code to HTML. The FOP documentation does
151 not meet those standard, so the conformance checks have to be
152 disabled. This can be done with the following command:
153 </para>
154
155<screen><userinput>sed -i '\@&lt;/javad@i\
156&lt;arg value="-Xdoclint:none"/&gt;\
157&lt;arg value="--allow-script-in-comments"/&gt;\
158&lt;arg value="--ignore-source-errors"/&gt;' \
159 fop/build.xml</userinput></screen>
160
161 <para>
162 The stack size set in <filename>build.xml</filename> for building the
163 hyphenation patterns is not enough. Change it by running:
164 </para>
165
166<screen><userinput>sed -e '/hyph\.stack/s/512k/1M/' \
167 -i fop/build.xml</userinput></screen>
168 <para>
169 Then, compile <application>fop</application> by running the
170 following commands:
171 </para>
172
173<screen><userinput>cd fop &amp;&amp;
174export LC_ALL=en_US.UTF-8 &amp;&amp;
175ant all javadocs &amp;&amp;
176mv build/javadocs .</userinput></screen>
177
178 <para>
179 To test the application, first modify <filename>build.xml</filename>
180 so that tests do not stop when an error is encountered:
181 </para>
182
183<screen><userinput>sed -e '/haltonfailure/s/yes/off/' \
184 -i build.xml</userinput></screen>
185
186 <para>
187 Then, run <command>ant junit</command>. The hyphenation tests will
188 fail if OFFO hyphenation has not been compiled. To see a list of other
189 test targets, use <command>ant -p</command>. You must run the tests
190 from an X-window using a GL-aware <application>Xorg</application>
191 server or some of the <application>JUnit</application> tests will hang.
192 </para>
193
194 <para>
195 Now, as the <systemitem class="username">root</systemitem> user:
196 </para>
197
198<screen role="root"><userinput>install -v -d -m755 -o root -g root /opt/fop-&fop-version; &amp;&amp;
199cp -v ../{KEYS,LICENSE,NOTICE,README} /opt/fop-&fop-version; &amp;&amp;
200cp -vR build conf examples fop* javadocs lib /opt/fop-&fop-version; &amp;&amp;
201chmod a+x /opt/fop-&fop-version;/fop &amp;&amp;
202
203ln -v -sfn fop-&fop-version; /opt/fop</userinput></screen>
204
205 </sect3>
206
207 </sect2>
208
209 <sect2 role="commands">
210 <title>Command Explanations</title>
211
212 <para>
213 <command>sed -i ... build.xml</command>: This adds two switches to the
214 <command>javadoc</command> command, preventing some errors to occur when
215 building the documentation.
216 </para>
217
218 <para>
219 <command>export LC_ALL=en_US.UTF-8</command>: the compiler fails if using
220 an ASCII locale.
221 </para>
222
223 <para>
224 <command>ant <option>target</option></command>: This reads the file
225 <filename>build.xml</filename> and builds the target: <option>compile
226 </option> compiles the java sources, <option>jar-main</option> generates
227 jar archives, <option>jar-hyphenation</option> generates the hyphenation
228 patterns for FOP, and <option>javadocs</option> builds the documentation.
229 </para>
230
231 <para>
232 <command>ln -v -sf fop-&fop-version; /opt/fop</command>: This is
233 optional and creates a convenience symlink so that
234 <envar>$FOP_HOME</envar> doesn't have to be changed each time there's a
235 package version change.
236 </para>
237
238 </sect2>
239
240 <sect2 role="configuration">
241 <title>Configuring fop</title>
242
243 <sect3 id="fop-config">
244 <title>Config Files</title>
245
246 <para>
247 <filename>~/.foprc</filename>
248 </para>
249
250 <indexterm zone="fop fop-config">
251 <primary sortas="e-AA.foprc">~/.foprc</primary>
252 </indexterm>
253
254 </sect3>
255
256 <sect3>
257 <title>Configuration Information</title>
258
259 <para>
260 Using <application>fop</application> to process some large FO's
261 (including the FO derived from the BLFS XML sources), can lead to
262 memory errors. Unless you add a parameter to the
263 <command>java</command> command used in the <command>fop</command>
264 script you may receive messages similar to the one shown below:
265 </para>
266
267 <para>
268 <computeroutput>
269 Exception in thread "main" java.lang.OutOfMemoryError: Java heap
270 space
271 </computeroutput>
272 </para>
273
274 <para>
275 To avoid errors like this, you need to pass an extra parameter to
276 the <command>java</command> command used in the <command>fop</command>
277 script. This can be accomplished by creating a
278 <filename>~/.foprc</filename> (which is sourced by the
279 <command>fop</command> script) and adding the parameter to the
280 <envar>FOP_OPTS</envar> environment variable.
281 </para>
282
283 <para>
284 The <command>fop</command> script looks for a
285 <envar>FOP_HOME</envar> environment variable to locate the
286 <application>fop</application> class libraries. You can create this
287 variable using the <filename>~/.foprc</filename> file as well. Create
288 a <filename>~/.foprc</filename> file using the following commands:
289 </para>
290
291<screen><userinput>cat &gt; ~/.foprc &lt;&lt; "EOF"
292<literal>FOP_OPTS="-Xmx<replaceable>&lt;RAM_Installed&gt;</replaceable>m"
293FOP_HOME="/opt/fop"</literal>
294EOF</userinput></screen>
295
296 <para>
297 Replace <replaceable>&lt;RAM_Installed&gt;</replaceable> with a
298 number representing the amount of RAM installed in your computer (in
299 megabytes). An example would be
300 <userinput>FOP_OPTS="-Xmx768m"</userinput>.
301 <!-- the URL is broken
302 For more information about
303 memory issues running <application>fop</application>, see
304 <ulink url="http://xml.apache.org/fop/running.html#memory"/>.
305 -->
306 </para>
307
308 <para>
309 To include the <command>fop</command> script in your path,
310 update the system-wide profile with the following command as the
311 <systemitem class="username">root</systemitem> user:
312 </para>
313
314<screen><literal>cat &gt; /etc/profile.d/fop.sh &lt;&lt; "EOF"
315# Begin /etc/profile.d/fop.sh
316
317pathappend /opt/fop
318
319# End /etc/profile.d/fop.sh
320EOF</literal></screen>
321
322 <note>
323 <para>
324 Running <command>fop</command> can be somewhat verbose.
325 The default logging level can be changed from INFO to any of
326 FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, ALL, or OFF.
327 To do this, edit
328 <filename>$JAVA_HOME/jre/lib/logging.properties</filename> and change
329 the entries for <option>.level</option> and
330 <option>java.util.logging.ConsoleHandler.level</option> to
331 the desired value.
332 </para>
333 </note>
334
335 </sect3>
336
337 </sect2>
338
339 <sect2 role="content">
340 <title>Contents</title>
341
342 <segmentedlist>
343 <segtitle>Installed Programs</segtitle>
344 <segtitle>Installed Libraries</segtitle>
345 <segtitle>Installed Directory</segtitle>
346
347 <seglistitem>
348 <seg>fop</seg>
349 <seg>fop.jar and numerous support library classes located in
350 <filename class='directory'>/opt/fop/{build,lib}</filename>; JAI
351 components include libmlib_jai.so, jai_codec.jar, jai_core.jar, and
352 mlibwrapper_jai.jar</seg>
353 <seg>/opt/fop-&fop-version;</seg>
354 </seglistitem>
355 </segmentedlist>
356
357 <variablelist>
358 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
359 <?dbfo list-presentation="list"?>
360 <?dbhtml list-presentation="table"?>
361
362 <varlistentry id="fop-prog">
363 <term><command>fop</command></term>
364 <listitem>
365 <para>is a wrapper script to the <command>java</command> command
366 which sets up the <application>fop</application>
367 environment and passes the required parameters.</para>
368 <indexterm zone="fop fop-prog">
369 <primary sortas="b-fop">fop</primary>
370 </indexterm>
371 </listitem>
372 </varlistentry>
373
374 <varlistentry id="fop.jar">
375 <term><filename class='libraryfile'>fop.jar</filename></term>
376 <listitem>
377 <para>contains all the <application>fop</application>
378 <application>Java</application> classes.</para>
379 <indexterm zone="fop fop.jar">
380 <primary sortas="c-fop.jar">fop.jar</primary>
381 </indexterm>
382 </listitem>
383 </varlistentry>
384
385 </variablelist>
386
387 </sect2>
388
389</sect1>
Note: See TracBrowser for help on using the repository browser.