Product SiteDocumentation Site

Chapter 5. Frequently Asked Questions

Q: How do I add a language to my book?
Q: How do I add another language to my book?
Q: What if I only use the country code? For example, OTHER_LANGS = en de fr?
Q: How do I update all po files?
Q: Where can I get a complete list of make targets?
Q: Where can I get a complete list of parameters that can be set in the Makefile?
Q: Where are the Publican common files located?
Q: Can I use the OASIS DocBook DTD for XML completion in editors such as Kate?
Q: I have extensive code samples for my book, how can I include them without having to xml escape everything?
Q: Is it possible to include arbitrary files in tar and RPM files?
Q: Why does publican give me warnings about unknown tags?
Q: How do I find out which tags have been tested in publican?
Q: Why does publican give me an error about banned tags?
Q: How do I find out which tags are banned in publican?
Q: Which brands enable STRICT mode?
Q: I get an error saying Batik is not in the classpath but batik is installed! What is wrong?
Q: I get an error Exception in thread "main" java.lang.OutOfMemoryError: Java heap space when trying to build PDF. What is wrong?
Q: Why does Jeff call Isaac Ivan?
How do I add a language to my book?
Edit your book's Makefile and uncomment the OTHER_LANGS entry. Add the required language code after the '=' sign.
How do I add another language to my book?
Append the language to OTHER_LANGS in the Makefile. Run the make update-po-language command. For example, make update-po-ja-JP creates the Japanese language directory and the Japanese po files.
What if I only use the country code? For example, OTHER_LANGS = en de fr?
Run the make update-po-en command.
How do I update all po files?
Run the make update-po-all command.
Where can I get a complete list of make targets?
Run the make help command.
Where can I get a complete list of parameters that can be set in the Makefile?
Run the make help_params command.
Where are the Publican common files located?
By default, they are in /usr/share/publican/.
Can I use the OASIS DocBook DTD for XML completion in editors such as Kate?
Yes. The OASIS DocBook DTD is included in the publican package, and is located here: /usr/share/publican/xsl/docbook.dtd.xml
I have extensive code samples for my book, how can I include them without having to xml escape everything?
The best way to do this is to create a directory named extras in your source language directory and use an xi:include to pull in the code file.
Procedure 5.1. Including code samples
  1. Create the extras directory 
    mkdir en-US/extras
  2. Copy the code file to the extras directory 
    cp ~/samples/foo.c en-US/extras/.
  3. xi:include the sample file in your xml file 
    <programlisting>
<xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
  4. You can now edit en-US/extras/foo.c in your favorite editor without having to be concerned about how it will affect the XML.
Is it possible to include arbitrary files in tar and RPM files?
Yes. If you make a directory named files in your source language directory it will be included in any tar or SRPM files created by publican.

Important

The files directory will not be available during the validation process so you can not xi:include or otherwise embed any files in this directory in your XML.
Why does publican give me warnings about unknown tags?
This warning informs you that you are using a tag whose output has not been tested for attractiveness, XHTML 1.0 Strict compliance, or Section 508 (Accessibility) compliance.
How do I find out which tags have been tested in publican?
Run xmlClean --known
Why does publican give me an error about banned tags?
This error indicates that the brand you are using has STRICT mode enabled for xmlClean and that the tag in question has been marked as undesirable. The error message should contain a reason why the tag was banned.
How do I find out which tags are banned in publican?
Run xmlClean --banned
Which brands enable STRICT mode?
Currently the Red Hat and JBoss brands enable STRICT mode.
I get an error saying Batik is not in the classpath but batik is installed! What is wrong?
We believe this is due to classpath issues caused by having different JRE and JDK versions installed. Sometimes this can be fixed by upgrading your JDK to the same version of your JRE.
Sometimes this issue can be revealed by running alternatives --config java and alternatives --config javac, if the versions are different then selecting the same version in both can fix this problem.
Some Java installs do not set-up the alternatives environment correctly, no fix has been determined for this situation.
I get an error Exception in thread "main" java.lang.OutOfMemoryError: Java heap space when trying to build PDF. What is wrong?
The default memory allocated for Java is not big enough to build your PDF. You need to increase the memory allocated to FOP. Before running make run echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc. This sets the initial heap space to 50MB and allows it to grow to a maximum of 700MB.
Why does Jeff call Isaac Ivan?
Because Jeff's memory is pants!