1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter id="chap-Users_Guide-Frequently_Asked_Questions">
<title>Frequently Asked Questions</title>
<qandaset>
<qandaentry>
<question>
<para>
How do I add a language to my book?
</para>
</question>
<answer>
<para>
Run <command>publican update_po --langs=<replaceable>language</replaceable></command>, where <replaceable>language</replaceable> 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, <command>publican update_po --langs=ja-JP</command> creates the Japanese language directory and Japanese PO files, and <command>publican update_po --langs=ja-JP,ko-KR</command> creates directories and PO files for both Japanese and Korean.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
What if I do not want to use the country code? For example, can I run <command>publican update_po --langs=es,de,fr</command>?
</para>
</question>
<answer>
<para>
Yes — this command works. However, if you omit the country code, the output might be unpredictable when <application>Publican</application> or a brand has definitions for more than one regional variety of a language — for example, <literal>zh-CN</literal> (Simplified Chinese as used in the People's Republic of China) and <literal>zh-TW</literal> (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 <application>Publican</application> does not suddenly cause your German (<literal>de-DE</literal>) documents to switch to Schweizerdeutsch (Swiss German, <literal>de-CH</literal>) Common Content and headings.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I update all po files?
</para>
</question>
<answer>
<para>
Run the <command>publican update_po --langs=all</command> command.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Where can I get a complete list of <application>Publican</application>'s build options?
</para>
</question>
<answer>
<para>
Run the <command>publican build --help</command> command.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Where can I get a complete list of parameters that can be set in the <filename>publican.cfg</filename>?
</para>
</question>
<answer>
<para>
Run the <command>publican help_config</command> command in a directory that holds any <application>Publican</application> document.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Where are the <application>Publican</application> common files located?
</para>
</question>
<answer>
<para>
By default, they are in <filename>/usr/share/publican/</filename> on Linux operating systems and in <filename>%SystemDrive%/%ProgramFiles%/publican/Common_Content</filename> on Windows operating systems — typically, <filename>C:/Program Files/publican/Common_Content</filename>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Is it possible to include arbitrary files in tarballs and RPM packages?
</para>
</question>
<answer>
<para>
Yes. If you make a directory named <filename>files</filename> in your source language directory it will be included in any tarballs or SRPM packages that <application>Publican</application> creates.
</para>
<important>
<title>Important</title>
<para>
The <filename>files</filename> directory will not be available during the validation process so you can not <sgmltag>xi:include</sgmltag> or otherwise embed any files in this directory in your XML.
</para>
</important>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Why does <application>Publican</application> give me warnings about unknown tags?
</para>
</question>
<answer>
<para>
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.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
<emphasis role="strikethrough">Which brands enable strict mode?</emphasis> Strict mode is not currently enforced.
</para>
</question>
<answer>
<para>
<emphasis role="strikethrough">Currently the Red Hat and JBoss brands enable strict mode.</emphasis>
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
I can build HTML documents fine, but when I try to build PDF documents, I get errors like <computeroutput>java.lang.NullPointerException</computeroutput> and no PDF file is produced. What is wrong?
</para>
</question>
<answer>
<para>
Try building a PDF version of a different document — perhaps a fresh one that you create with the <command>publican create</command> command. If the problem is not just with one particular document, you probably have a mismatch between the <application>Java Runtime Environment</application> (JRE) and the <application>Java Development Kit</application> (JDK) in use on your system. If you have a JDK installed, <application>FOP</application> requires that the JDK is of the same version as the JRE. Furthermore, <application>FOP</application> cannot use the <application>GNU Compiler for Java</application> (GCJ).
</para>
<para>
Run <command>alternatives --config java</command> and <command>alternatives --config javac</command> to determine which JRE and JDK are in use, then select versions that match and which do not have <literal>gcj</literal> in their name. For example, the following Java configuration shows a matching JRE and JDK that allow PDFs to build:
</para>
<screen>$ 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:</screen>
<screen>$ 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: </screen>
<para>
You might need to install an extra JDK if you do not have a JDK on your system that matches any of the JREs.
</para>
<para>
Some Java installations do not set up the <command>alternatives</command> environment correctly. No fix has been determined for this situation.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
I get an error saying <application>Batik</application> is not in the classpath but <application>Batik</application> is installed! What is wrong?
</para>
</question>
<answer>
<para>
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 <computeroutput>java.lang.NullPointerException</computeroutput> errors and using the <command>alternatives</command> command to ensure that the JRE and JDK match.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
I get an error <computeroutput>Exception in thread "main" java.lang.OutOfMemoryError: Java heap space</computeroutput> when trying to build PDF. What is wrong?
</para>
</question>
<answer>
<para>
The default memory allocated for Java is not big enough to build your PDF. You need to increase the memory allocated to <application>FOP</application>. Before running <command>publican build</command> run <command>echo "FOP_OPTS='-Xms50m -Xmx700m'" > ~/.foprc</command>. This sets the initial heap space to 50 MB and allows it to grow to a maximum of 700 MB.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Previous versions of <application>Publican</application> removed empty <sgmltag><para></sgmltag> tags. Does <application>Publican</application> still do this?
</para>
</question>
<answer>
<para>
No. <application>Publican</application> previously removed empty <sgmltag><para></sgmltag> tags while it transformed XML because empty <sgmltag><para></sgmltag> tags broke earlier translation toolchains used within Red Hat and the Fedora Project. Empty <sgmltag><para></sgmltag> tags are valid DocBook XML, and <application>Publican</application> no longer removes them.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
What happened to the spell check?
</para>
</question>
<answer>
<para>
Early versions of <application>Publican</application> (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.
</para>
<para>
Run the following bash script in the root directory of your document to check spellings in your XML files with the <application>aspell</application> command-line spell checker.
</para>
<programlisting language="Bash"><xi:include href="extras/proof.sh" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Why don't <sgmltag><segmentedlist></sgmltag>s work when I build PDFs?
</para>
</question>
<answer>
<para>
Check the number of columns in your <sgmltag><segmentedlist></sgmltag>s. When <sgmltag><segmentedlist></sgmltag>s are formatted as tables, the DocBook XSL limits the number of columns to two, and <application>Publican</application> formats <sgmltag><segmentedlist></sgmltag>s as tables.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
What happened to the colors in my images in this PDF?
</para>
</question>
<answer>
<para>
This is the result of a bug in <application>FOP</application> that distorts colors in 24-bit PNG images. Convert your images to 32-bit PNG images to work around the problem.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
When I build my document, I get an error about an ‘undefined language’ — what's wrong?
</para>
</question>
<answer>
<para>
Code highlighting in <application>Publican</application> is generated with the <application>Syntax::Highlight::Engine::Kate</application> Perl module. If you specify a language in a <sgmltag><programlisting></sgmltag> tag that <application>Syntax::Highlight::Engine::Kate</application> does not recognize, you receive an error when you build your book. The first lines of the error message are similar to:
</para>
<screen><computeroutput>undefined language: JAVA at /usr/lib/perl5/vendor_perl/5.10.0/Syntax/Highlight/Engine/Kate.pm</computeroutput>
<computeroutput>line 615.</computeroutput>
<computeroutput>cannot create plugin for language 'JAVA'</computeroutput>
</screen>
<para>
Note that <application>Syntax::Highlight::Engine::Kate</application> is very strict about names of languages and is case sensitive. Therefore, <sgmltag><programlisting language="Java"></sgmltag> works, but <sgmltag><programlisting language="java"></sgmltag> and <sgmltag><programlisting language="JAVA"></sgmltag> do not. The error message that you receive identifies the problematic language attribute.
</para>
<para>
Refer to <ulink url="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 <application>Syntax::Highlight::Engine::Kate</application> supports, including their expected capitalization and punctuation.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
How do I enable bash command-line completion for Publican?
</para>
</question>
<answer>
<para>
Support for bash command-line completion is a new feature in <application>Publican 2.2</application>. To enable this feature:
</para>
<procedure>
<step>
<para>
Install the package or packages that provide bash completion for your operating system. For example, on Fedora, run <command>sudo yum install bash-completion</command>.
</para>
</step>
<step>
<para>
Add the following to your <filename>~/.bashrc</filename> file:
</para>
<programlisting language="Bash">
# Use bash-completion, if available
if [ -f /etc/bash_completion ]; then
. /etc/bash_completion
fi
</programlisting>
</step>
<step>
<para>
Restart your terminal or run <command>source ~/.bashrc</command>.
</para>
</step>
</procedure>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
Why does Jeff call Isaac ‘Ivan’?
</para>
</question>
<answer>
<para>
Because Jeff's memory is pants!
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>
|
