source: pst/ps/fop.xml@ ba7be716

10.0 10.1 11.0 11.1 11.2 8.0 8.1 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind lazarus perl-modules qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since ba7be716 was ba7be716, checked in by Pierre Labastie <pieere@…>, 6 years ago

Fix javadoc in fop

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

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