Product SiteDocumentation Site

Chapter 6. Frequently Asked Questions

Q: How do I add a language to my book?
Q: What if I do not want to use the country code? For example, can I run publican update_po --langs=es,de,fr?
Q: How do I update all po files?
Q: Where can I get a complete list of Publican's build options?
Q: Where can I get a complete list of parameters that can be set in the publican.cfg?
Q: Where are the Publican common files located?
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 tarballs and RPM packages?
Q: Why does Publican give me warnings about unknown tags?
Q: Which brands enable strict mode? Strict mode is no longer enforced.
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: Previous versions of Publican removed empty <para> tags. Does Publican still do this?
Q: What happened to the spell check?
Q: Why don't <segmentedlist>s work when I build PDFs?
Q: What happened to the colors in my images in this PDF?
Q: When I build my document, I get an error about an ‘undefined language’ — what's wrong?
Q: Why does Jeff call Isaac ‘Ivan’?
How do I add a language to my book?
Run publican update_po --langs=language, where language is the code for the new language that you want to add. You can add more than one language at a time, with the language codes separated by commas. For example, publican update_po --langs=ja-JP creates the Japanese language directory and Japanese PO files, and publican update_po --langs=ja-JP,ko-KR creates directories and PO files for both Japanese and Korean.
What if I do not want to use the country code? For example, can I run publican update_po --langs=es,de,fr?
Yes — this command works. However, if you omit the country code, the output might be unpredictable when Publican or a brand has definitions for more than one regional variety of a language — for example, zh-CN (Simplified Chinese as used in the People's Republic of China) and zh-TW (Traditional Chinese as used in the Republic of China, on Taiwan). Even when only one variety is currently defined, it is always safest to include the country code so that, for example, a future update of Publican does not suddenly cause your German (de-DE) documents to switch to Schweizerdeutsch (Swiss German, de-CH) Common Content and headings.
How do I update all po files?
Run the publican update_po --langs=all command.
Where can I get a complete list of Publican's build options?
Run the publican build --help command.
Where can I get a complete list of parameters that can be set in the publican.cfg?
Run the publican help_config command in a directory that holds any Publican document.
Where are the Publican common files located?
By default, they are in /usr/share/publican/ on Linux operating systems and in %SystemDrive%/%ProgramFiles%/publican/Common_Content on Windows operating systems — typically, C:/Program Files/publican/Common_Content.
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 6.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 tarballs and RPM packages?
Yes. If you make a directory named files in your source language directory it will be included in any tarballs or SRPM packages that Publican creates.

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.
Which brands enable strict mode? Strict mode is no longer enforced.
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 50 MB and allows it to grow to a maximum of 700 MB.
Previous versions of Publican removed empty <para> tags. Does Publican still do this?
No. Publican previously removed empty <para> tags while it transformed XML because empty <para> tags broke earlier translation toolchains used within Red Hat and the Fedora Project. Empty <para> tags are valid DocBook XML, and Publican no longer removes them.
What happened to the spell check?
Early versions of Publican (up to and including 0.45) ran a spell check while transforming a document's XML. Due to negative feedback from users, this feature was dropped.
Why don't <segmentedlist>s work when I build PDFs?
Check the number of columns in your <segmentedlist>s. When <segmentedlist>s are formatted as tables, the DocBook XSL limits the number of columns to two, and Publican formats <segmentedlist>s as tables.
What happened to the colors in my images in this PDF?
This is the result of a bug in FOP that distorts colors in 24-bit PNG images. Convert your images to 32-bit PNG images to work around the problem.
When I build my document, I get an error about an ‘undefined language’ — what's wrong?
Code highlighting in Publican is generated with the Syntax::Highlight::Engine::Kate Perl module. If you specify a language in a <programlisting> tag that Syntax::Highlight::Engine::Kate does not recognize, you receive an error when you build your book. The first lines of the error message are similar to: 
undefined language: JAVA at /usr/lib/perl5/vendor_perl/5.10.0/Syntax/Highlight/Engine/Kate.pm line 615.
cannot create plugin for language 'JAVA'
Note that Syntax::Highlight::Engine::Kate is very strict about names of languages and is case sensitive. Therefore, <programlisting language="Java"> works, but <programlisting language="java"> and <programlisting language="JAVA"> do not. The error message that you receive identifies the problematic language attribute.
Refer to http://search.cpan.org/~szabgab/Syntax-Highlight-Engine-Kate-0.06/lib/Syntax/Highlight/Engine/Kate.pm#PLUGINS for the full list of languages that Syntax::Highlight::Engine::Kate supports, including their expected capitalization and punctuation.
Why does Jeff call Isaac ‘Ivan’?
Because Jeff's memory is pants!