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
|
<?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>
I have extensive code samples for my book, how can I include them without having to XML escape everything?
</para>
</question>
<answer>
<para>
The best way to do this is to create a directory named <filename>extras</filename> in your source language directory and use an <sgmltag>xi:include</sgmltag> to pull in the code file.
</para>
<procedure id="proc-Users_Guide-Frequently_Asked_Questions-Including_code_samples">
<title>Including code samples</title>
<step>
<para>
Create the extras directory
</para>
<screen><command>mkdir <filename>en-US/extras</filename></command>
</screen>
</step>
<step>
<para>
Copy the code file to the extras directory
</para>
<screen><command>cp <filename>~/samples/foo.c en-US/extras/.</filename></command>
</screen>
</step>
<step>
<para>
<sgmltag>xi:include</sgmltag> the sample file in your xml file
</para>
<programlisting language="XML"><programlisting>
<xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" />
</programlisting>
</programlisting>
</step>
<step>
<para>
You can now edit <filename>en-US/extras/foo.c</filename> in your favorite editor without having to be concerned about how it will affect the XML.
</para>
</step>
</procedure>
</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 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 installed. Sometimes this can be fixed by upgrading your JDK to the same version of your JRE.
</para>
<para>
Sometimes this issue can be revealed by running <command>alternatives --config java</command> and <command>alternatives --config javac</command>, if the versions are different then selecting the same version in both can fix this problem.
</para>
<para>
Some Java installs 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 <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>make </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>
</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 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>
Why does Jeff call Isaac ‘Ivan’?
</para>
</question>
<answer>
<para>
Because Jeff's memory is pants!
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>
|
