Product SiteDocumentation Site

Chapter 9. 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: Is it possible to include arbitrary files in tarballs and RPM packages?
Q: Why does Publican give me warnings about unknown tags?
Q: I can build HTML documents fine, but when I try to build PDF documents, I get errors like java.lang.NullPointerException and no PDF file is produced. What is wrong?
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: How do I enable bash command-line completion for Publican?
Q: Why am I having trouble building my large book?
Q: Why does Jeff call Isaac ‘Ivan’?
Q:
How do I add a language to my book?
A:
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.
Q:
What if I do not want to use the country code? For example, can I run $ publican update_po --langs=es,de,fr?
A:
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.
Q:
How do I update all po files?
A:
Run the $ publican update_po --langs=all command.
Q:
Where can I get a complete list of Publican's build options?
A:
Run the $ publican build --help command.
Q:
Where can I get a complete list of parameters that can be set in the publican.cfg?
A:
Run the $ publican help_config command in a directory that holds any Publican document.
Q:
Where are the Publican common files located?
A:
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.
Q:
Is it possible to include arbitrary files in tarballs and RPM packages?
A:
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.
Q:
Why does Publican give me warnings about unknown tags?
A:
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.
Q:
I can build HTML documents fine, but when I try to build PDF documents, I get errors like java.lang.NullPointerException and no PDF file is produced. What is wrong?
A:
Try building a PDF version of a different document — perhaps a fresh one that you create with the $ publican create command. If the problem is not just with one particular document, you probably have a mismatch between the Java Runtime Environment (JRE) and the Java Development Kit (JDK) in use on your system. If you have a JDK installed, FOP requires that the JDK is of the same version as the JRE. Furthermore, FOP cannot use the GNU Compiler for Java (GCJ).
Run alternatives --config java and alternatives --config javac to determine which JRE and JDK are in use, then select versions that match and which do not have gcj in their name. For example, the following Java configuration shows a matching JRE and JDK that allow PDFs to build:
$ alternatives --config java

There are 3 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.5.0-gcj/bin/java
*  2           /usr/lib/jvm/jre-1.6.0-openjdk/bin/java
 + 3           /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin/java

Enter to keep the current selection[+], or type selection number:
$ alternatives --config javac

There are 3 programs which provide 'javac'.

  Selection    Command
-----------------------------------------------
*+ 1           /usr/lib/jvm/java-1.6.0-openjdk.x86_64/bin/javac
   2           /usr/lib/jvm/java-1.6.0-openjdk/bin/javac
   3           /usr/lib/jvm/java-1.5.0-gcj/bin/javac

Enter to keep the current selection[+], or type selection number:
You might need to install an extra JDK if you do not have a JDK on your system that matches any of the JREs.
Some Java installations do not set up the alternatives environment correctly. No fix has been determined for this situation.
Q:
I get an error saying Batik is not in the classpath but Batik is installed! What is wrong?
A:
We believe this is due to classpath issues caused by having different JRE and JDK versions in use. Refer to the previous question in this FAQ about java.lang.NullPointerException errors and using the alternatives command to ensure that the JRE and JDK match.
Q:
I get an error Exception in thread "main" java.lang.OutOfMemoryError: Java heap space when trying to build PDF. What is wrong?
A:
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 $ publican build 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.
Q:
Previous versions of Publican removed empty <para> tags. Does Publican still do this?
A:
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.
Q:
What happened to the spell check?
A:
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.
Run the following bash script in the root directory of your document to check spellings in your XML files with the aspell command-line spell checker.
#!/bin/sh
# Jeff Fearn 2010

ASPELL_EXCLUDES=programlisting,userinput,screen,filename,command,computeroutput,abbrev,accel,orgname,surname,foreignphrase,acronym,hardware

for file in `find en-US -wholename '*/extras/*' -prune -o -name \*.xml -print`; do
	echo "Processing $file";
	aspell --list --lang=en-US --mode=sgml --add-sgml-skip={$ASPELL_EXCLUDES} < $file  | sort -u;
	echo;
done


Q:
Why don't <segmentedlist>s work when I build PDFs?
A:
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.
Q:
What happened to the colors in my images in this PDF?
A:
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.
Q:
When I build my document, I get an error about an ‘undefined language’ — what's wrong?
A:
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/dist/Syntax-Highlight-Engine-Kate/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.
Q:
How do I enable bash command-line completion for Publican?
A:
Support for bash command-line completion is a new feature in Publican 2.2. To enable this feature:
  1. Install the package or packages that provide bash completion for your operating system. For example, on Fedora, run sudo yum install bash-completion.
  2. Add the following to your ~/.bashrc file:
    
    # Use bash-completion, if available
    if [ -f /etc/bash_completion ]; then
            . /etc/bash_completion
    fi
    
  3. Restart your terminal or run source ~/.bashrc.
Q:
Why am I having trouble building my large book?
A:
Probably because the kernel can deal with only a certain number of file handles at a time, and you have exceeded that number. On some linuxes you can run ulimit -n 8192 to change the limit for the current shell.
To make this permanent, open /etc/security/limits.conf and add these two lines:
*                 soft    nofile          8192
*                 hard    nofile          8192
Then save, and log in again for the changes to take effect.
Q:
Why does Jeff call Isaac ‘Ivan’?
A:
Because Jeff's memory is pants!