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
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<section conformance="193" version="5.0" xml:id="sect-Publican-Users_Guide-Packaging_a_document" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info>
<title>Packaging a document</title>
</info>
<xi:include href="Applicable_to_RPM_only.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<note conformance="234">
<info>
<title>Note — Customizing output</title>
</info>
<para>
The parameters set in the document configuration file (by default, <filename>publican.cfg</filename>) allow you to control many aspects of the way in which a document is presented and packaged — refer to <xref linkend="sect-Publican-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" />.
</para>
<para>
If you maintain multiple versions of a document, you can create a configuration file for each version. When packaging the document, you can use the <option>--config</option> to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example:
</para>
<screen><prompt>$</prompt> <command>publican package --lang hi-IN --config community.cfg</command></screen>
</note>
<para>
<application>Publican</application> not only builds documentation, but it can package built content for distribution to individual workstations and to web servers as <firstterm>RPM packages</firstterm>. RPM packages are used to distribute software to computers with Linux operating systems that use the <application>RPM Package Manager</application>. These operating systems include Red Hat Enterprise Linux, Fedora, Mandriva Linux, SUSE Linux Enterprise, openSUSE, Turbolinux, and Yellow Dog Linux, to name just a few.
</para>
<section conformance="194" xml:id="sect-Publican-Users_Guide-Packaging_a_document-Types_of_RPM_packages">
<info>
<title>Types of RPM packages</title>
</info>
<para>
<application>Publican</application> can produce both <firstterm>source RPM packages</firstterm> (<firstterm>SRPM packages</firstterm>) and <firstterm>binary RPM packages</firstterm>. Furthermore, both SRPM packages and binary RPM packages can be configured to deploy to workstations or web servers.
</para>
<section conformance="195" xml:id="sect-Publican-Users_Guide-Types_of_RPM_packages-Source_RPM_packages_and_binary_RPM_packages">
<info>
<title>Source RPM packages and binary RPM packages</title>
</info>
<para>
SRPM packages contain the source code used to generate software rather than the software itself. To use an SRPM package, a computer must <firstterm>compile</firstterm> the source code into software — or in this case, into documents. SRPM packages of <application>Publican</application> documents contain XML files and a <firstterm>spec file</firstterm> rather than finished documents in formats such as HTML and PDF. You cannot install documentation directly from SRPM packages with current versions of the <application>RPM Package Manager</application>.
</para>
<para>
Conversely, binary RPM packages contain software — or in this case, a document — that is ready to copy to a location in the computer's file system and use immediately. The contents of the binary RPM package do not need to be compiled by the computer onto which they are installed. Therefore, when installing documentation solely for local use the computer does not need to have <application>Publican</application> installed. Installing <application>Publican</application>-generated documentation on a webserver <emphasis>does</emphasis> requires <application>Publican</application> to be installed, but for reasons other than compiling the source code. Refer to <xref linkend="sect-Publican-Users_Guide-Types_of_RPM_packages-Desktop_packages_and_web_packages" /> for a description of the differences between documentation installed for local use (<firstterm>desktop RPMs</firstterm>) and documentation installed to serve as web content (<firstterm>web RPMs</firstterm>).
</para>
</section>
<section conformance="196" xml:id="sect-Publican-Users_Guide-Types_of_RPM_packages-Desktop_packages_and_web_packages">
<info>
<title>Desktop packages and web packages</title>
</info>
<para>
<application>Publican</application> can package documents for reading on a computer workstation (a <firstterm>desktop RPM package</firstterm>) or to install on a web server and publish on the World Wide Web (a <firstterm>web RPM package</firstterm>). The desktop RPM package of a <application>Publican</application> document and the web RPM package of the same document differ in that the desktop RPM package installs documentation only for local use on a computer, while the web RPM installs documentation for local use, but also to be served to the World Wide Web.
</para>
<para>
Desktop (binary) RPM packages of <application>Publican</application> documents contain the documentation in single-page HTML format. Documents distributed in these packages are installed in a subdirectory of <filename>/usr/share/doc/</filename>, the location specified by the <citetitle>Filesystem Hierarchy Standard</citetitle> (<citetitle>FHS</citetitle>) for ‘Miscellaneous documentation’.<footnote> <para>
Refer to <link xlink:href="http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA" xmlns:xlink="http://www.w3.org/1999/xlink">http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA</link>
</para>
</footnote> The desktop RPM package also contains a <firstterm>desktop file</firstterm>, to be placed in <filename>/usr/share/applications/</filename>. This file enables <firstterm>desktop environments</firstterm> to add the installed document to their menus for ease of reference by users. By default, the menu item appears under <menuchoice><guimenu>System</guimenu><guisubmenu>Documentation</guisubmenu></menuchoice> on the GNOME desktop. To customize the placement of the menu item, create a documentation menu package to supply <filename>.directory</filename> and <filename>.menu</filename> files and set the <parameter>dt_requires</parameter> and <parameter>menu_category</parameter> parameters in the <filename>publican.cfg</filename> file to require this package and supply the appropriate menu category. Refer to <xref linkend="sect-Publican-Users_Guide-Desktop_menu_entries_for_documents" />
</para>
<para>
By default, web RPM packages of <application>Publican</application> documents contain the documentation in single-page HTML, multi-page HTML, EPUB, and PDF formats. The formats included vary if:
</para>
<itemizedlist>
<listitem>
<para>
you publish documentation in a language in which PDF output is not currently supported. <application>Publican</application> relies on <application>FOP</application> to generate PDF output. <application>FOP</application> does not presently support right-to-left text (for example, Arabic, Persian, or Hebrew). Furthermore, because <application>FOP</application> cannot presently specify fonts on a character-by-character basis, a lack of available fonts in Indic scripts that also include Latin glyphs prevents <application>Publican</application> from reliably generating PDF output in Indic languages. By default, <application>Publican</application> does not include PDF files in web RPM packages generated in Arabic, Persian, Hebrew, or any Indic language.
</para>
</listitem>
<listitem>
<para>
your book or your brand contains the <parameter>web_formats</parameter> parameter. The value of this parameter overrides the default formats that <application>Publican</application> packages. For example, to publish the document only as single-page HTML, PDF, and text, set <literal>web_formats: "html-single,pdf,txt"</literal>
</para>
</listitem>
</itemizedlist>
<para>
Built content is installed in subdirectories of <filename>/var/www/html/</filename>, a common <firstterm>document root</firstterm> for web servers. Note that the web SRPM package generates both a web binary RPM package and desktop binary RPM package.
</para>
</section>
<xi:include href="Desktop_menus.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</section>
<section conformance="197" xml:id="sect-Publican-Users_Guide-Packaging_a_document-The_publican_package_command">
<info>
<title>The <prompt>$</prompt> <command>publican package</command> command</title>
</info>
<para>
Use the <prompt>$</prompt> <command>publican package --lang=<replaceable>Language_Code</replaceable></command> command to package documents for distribution in the language that you specify with the <option>--lang</option> option. Refer to <xref linkend="appe-Publican-Users_Guide-Language_codes" /> for more information about language codes.
</para>
<para>
If you run <prompt>$</prompt> <command>publican package</command> with no options other than the mandatory <option>--lang</option> option, <application>Publican</application> produces a web SRPM package. The full range of options for <command>publican package</command> is as follows:
</para>
<variablelist>
<varlistentry>
<term><option>--lang</option> <replaceable>language</replaceable></term>
<listitem>
<para>
specifies the language in which to package the documentation.
</para>
<note>
<info>
<title>Incomplete translations</title>
</info>
<para>
If translation in a particular language is not complete by the scheduled release date, consider marking the language with the <parameter>ignored_translations</parameter> parameter in the document's <filename>publican.cfg</filename> file. The package will be named appropriately for the language, but will contain documentation in the original language of the XML rather than a partial translation. When translation is complete, remove the <parameter>ignored_translations</parameter> parameter, increase the release number in the <literal>Project-Id-Version</literal> field in the <filename>Book_Info.po</filename> file for that language, and generate the package again. When you distribute the revised package, it becomes available to replace the original untranslated package.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--config</option> <replaceable>filename</replaceable></term>
<listitem>
<para>
specifies that <application>Publican</application> should use a configuration file other than the default <filename>publican.cfg</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--desktop</option></term>
<listitem>
<para>
specifies that <application>Publican</application> should create a desktop RPM package rather than a web RPM package.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--brew</option></term>
<listitem>
<para>
specifies that <application>Publican</application> should push the completed package to <application>Brew</application>. <application>Brew</application> is the build system used internally by Red Hat; this option is meaningless outside Red Hat.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--scratch</option></term>
<listitem>
<para>
when used together with the <option>--brew</option> and <option>--desktop</option> options, specifies that an SRPM package should be built as a <firstterm>scratch build</firstterm> when sent to <application>Brew</application>. Scratch builds are used to verify that an SRPM package is structured correctly, without updating the package database to use the resulting package.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--short_sighted</option></term>
<listitem>
<para>
specifies that <application>Publican</application> should build the package without including the version number of the software (<parameter>version</parameter> in the <filename>publican.cfg</filename> file) in the package name.
</para>
<warning>
<info>
<title>Omitting the software version number</title>
</info>
<para>
Much software documentation is version-specific. At best, the procedures described in the documentation for one version of a product might not help you to install, configure, or use a different version of the product. At worst, the procedures described in the documentation for one version might be misleading or even harmful when applied to a different version.
</para>
<para>
If you distribute documentation as RPM packages without version numbers in the package names, the <application>RPM Package Manager</application> on users' computers will automatically replace any existing documentation with the documentation for the latest version; users will not have access to documentation for more than one version of the software at a time. Be certain you want this outcome.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--binary</option></term>
<listitem>
<para>
specifies that <application>Publican</application> should build the package as a binary RPM package.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
After you run the <prompt>$</prompt> <command>publican package</command> command, <application>Publican</application> outputs completed SRPM packages to the document's <filename>tmp/rpm</filename> directory, and completed binary RPM packages to the document's <filename>tmp/rpm/noarch</filename> directory.
</para>
<para>
By default, <application>Publican</application> documentation packages are named:
</para>
<literallayout><filename><replaceable>productname</replaceable>-<replaceable>title</replaceable>-<replaceable>productnumber</replaceable>-<replaceable>[web]-</replaceable><replaceable>language</replaceable>-<replaceable>edition</replaceable>-<replaceable>pubsnumber</replaceable>. <replaceable>[.[build_target].noarch]</replaceable>.<replaceable>file_extension</replaceable></filename>.</literallayout>
<para>
<application>Publican</application> uses the information in the document's configuration file (by default, <filename>publican.cfg</filename>) to supply the various parameters in the file name, and then information in the <filename>Book_Info.xml</filename> file for any parameters missing from the configuration file. Refer to <xref linkend="sect-Publican-Users_Guide-Files_in_the_book_directory" /> for details of the parameters used in these files. Additionally, note that:
</para>
<itemizedlist>
<listitem>
<para>
web RPM packages include the element <literal>-web-</literal> between the product version and the language code.
</para>
</listitem>
<listitem>
<para>
SRPM packages have the file extension <literal>.src.rpm</literal> but binary RPM packages have the file extension <literal>.rpm</literal>
</para>
</listitem>
<listitem>
<para>
binary RPM packages include <literal><replaceable>build_target</replaceable>.noarch</literal> before the file extension, where <replaceable>build_target</replaceable> represents the operating system and version that the package is built for as set by the <parameter>os_ver</parameter> parameter in the <filename>publican.cfg</filename> file. The <literal>noarch</literal> element specifies that the package can be installed on any system, regardless of the system architecture.
</para>
</listitem>
<listitem>
<para>
use of the <option>--short_sighted</option> option removes the <literal>-<replaceable>productnumber</replaceable>-</literal> from the package name.
</para>
</listitem>
<listitem>
<para>
packages of translated documents take their release numbers from the <parameter>Project-Id-Version</parameter> parameter in the <filename>Article_Info.po</filename> or <filename>Book_Info.po</filename> file. This release number is specific to a particular language and bears no relationship to the release numbers of the same document in the original language or any other language.
</para>
</listitem>
</itemizedlist>
<section conformance="198" xml:id="sect-Publican-Users_Guide-The_publican_package_command-The_publican_package_command_Example_usage">
<info>
<title>The <prompt>$</prompt> <command>publican package</command> command — Example usage</title>
</info>
<para>
The following examples illustrate some common options, illustrated with the <citetitle>Foomaster 9 Configuration Guide</citetitle>, edition 2, revision 6.
</para>
<variablelist>
<varlistentry>
<term><prompt>$</prompt> <command>publican package --lang=cs-CZ</command></term>
<listitem>
<para>
produces a web SRPM package named <package>Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.src.rpm</package> that contains XML source files in Czech, together with a spec file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <command>publican package --desktop --lang=cs-CZ</command></term>
<listitem>
<para>
produces a desktop SRPM package named <package>Foomaster-Configuration_Guide-9-cs-CZ-2-6.src.rpm</package> that contains XML source files in Czech, together with a spec file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <command>publican package --binary --lang=cs-CZ</command></term>
<listitem>
<para>
produces both a web binary RPM package named <package>Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.el5.noarch.rpm</package> and a desktop binary RPM package named <package>Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm</package> that contain documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <command>publican package --desktop --binary --lang=cs-CZ</command></term>
<listitem>
<para>
produces a desktop binary RPM package named <package>Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm</package> that contains documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <command>publican package --desktop --short_sighted --lang=cs-CZ</command></term>
<listitem>
<para>
produces a desktop SRPM package named <package>Foomaster-Configuration_Guide-cs-CZ-2-6.src.rpm</package> that contains documentation in Czech. This package will replace any Configuration Guides for previous versions of <application>Foomaster</application> that exists on a system. Users cannot have access to both the <citetitle>Foomaster 8 Configuration Guide</citetitle> and the <citetitle>Foomaster 9 Configuration Guide</citetitle>.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
|
