3.5. Packaging a book

Packages other than RPM packages

This section discusses packaging documents for distribution through the RPM Package Manager. However, when you use the publican package command, Publican generates a tarball that you can use to build a package to distribute through different package manager software. If you run publican package on a computer on which rpmbuild is not installed, Publican still generates the tarball, even though it cannot then generate an RPM package from that tarball.

Publican not only builds documentation as HTML and PDF files, but it can package these files for distribution to individual workstations and to web servers as RPM packages. RPM packages are used to distribute software to computers with Linux operating systems that use the RPM Package Manager. 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.

3.5.1. Types of RPM packages

Publican can produce both source RPM packages (SRPM packages) and binary RPM packages. Furthermore, both SRPM packages and binary RPM packages can be configured to deploy to workstations or web servers.

3.5.1.1. Source RPM packages and binary RPM packages

An SRPM package contains the source code used to generate software rather than the software itself. To use an SRPM package, a computer must compile the source code into software — or in this case, into documents. SRPM packages of Publican documents contain XML files rather than finished documents. To install documentation from the SRPM package to a computer, the computer must have Publican installed on it. When you try to install the SRPM package on a computer that does not have Publican installed, the RPM Package Manager looks for Publican in the software repositories that are available to it. The RPM Package Manager installs Publican first, so that it can build and install the document contained in the SRPM package. If the RPM Package Manager cannot find and install Publican, installation of the SRPM package will fail.

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, and therefore, the computer does not need to have Publican installed.

3.5.1.2. Desktop packages and web packages

Publican can package documents for reading on a computer workstation (a desktop RPM package) or to install on a web server and publish on the world-wide web (a web RPM package). The desktop RPM package of a Publican 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.

Desktop RPM packages of Publican documents contain the documentation in single-page HTML format. Documents distributed in these packages are installed in a subdirectory of /usr/share/doc/, the location specified by the Filesystem Hierarchy Standard (FHS) for ‘Miscellaneous documentation’.^[2] The desktop RPM package also contains a desktop file, to be placed in /usr/share/applications/. This file enables desktop environments such as GNOME and KDE to add the installed document to their menus for ease of reference by users.

Web RPM packages of Publican documents contain the documentation in single-page HTML, multi-page HTML, and PDF formats. They are installed in a subdirectory of /var/www/html/, a common document root for web servers. Note that the web SRPM package generates both a web binary RPM package and desktop binary RPM package.

3.5.2. The `publican package` command

Use the publican package --lang=Language_Code command to package documents for distribution in the language that you specify with the --lang option. Refer to Appendix D, Language codes for more information about language codes.

If you run publican package with no options other than the mandatory --lang option, Publican produces a web SRPM package. The full range of options for publican package is as follows:

--lang: specifies the language in which to package the documentation.
Incomplete translations
If translation in a particular language is not complete by the scheduled release date, consider marking the language with the ignored_translations parameter in the document's publican.cfg 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 ignored_translations parameter, increase the release number in the Project-Id-Version field in the Book_Info.po file for that language, and generate the package again. When you distribute the revised package, it becomes available to replace the original untranslated package.
--desktop: specifies that Publican should create a desktop RPM package rather than a web RPM package.
--brew: specifies that Publican should push the completed package to Brew. Brew is the build system used internally by Red Hat; this option is meaningless outside Red Hat.
--scratch: when used together with the --brew and --desktop options, specifies that a SRPM package should be built as a scratch build when sent to Brew. Scratch builds are used to verify that an SRPM package is structured correctly, without updating the package database to use the resulting package.
--short_sighted: specifies that Publican should build the package without including the version number of the software (version in the publican.cfg file) in the package name.
Omitting the software version number
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.
If you distribute documentation as RPM packages without version numbers in the package names, the RPM Package Manager 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.
--binary: specifies that Publican should build the package as a binary RPM package.

After you run the publican package command, Publican outputs completed SRPM packages to the document's tmp/rpm directory, and completed binary RPM packages to the document's tmp/rpm/noarch directory.

By default, Publican documentation packages are named productname-title-productnumber-[web]-language-edition-pubsnumber.[build_target].noarch.file_extension. Publican uses the information in the document's publican.cfg file to supply the various parameters in the file name, and then information in the Book_Info.xml file for any parameters missing from the publican.cfg file. Refer to Section 3.1, “Files in the book directory” for details of configuring these files. Additionally:

web RPM packages include the element -web- between the product version and the language code.
SRPM packages have the file extension .src.rpm but binary RPM packages have the file extension .rpm
binary RPM packages include [build_target].noarch before the file extension, where [build_target] represents the operating system and version that the package is built for as set by the os_ver parameter in the publican.cfg file. The noarch element specifies that the package can be installed on any system, regardless of the system architecture.
use of the --short_sighted option removes the -productnumber- from the package name.

3.5.2.1. The `publican package` command — Example usage

The following examples illustrate some common options, illustrated with the Foomaster 9 Configuration Guide, edition 2, revision 6.

publican package --lang=cs-CZ: produces a web SRPM package named Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.src.rpm that contains documentation in Czech.
publican package --desktop --lang=cs-CZ: produces a desktop SRPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.src.rpm that contains documentation in Czech.
publican package --binary --lang=cs-CZ: produces both a web binary RPM package named Foomaster-Configuration_Guide-9-web-cs-CZ-2-6.el5.noarch.rpm and a desktop binary RPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm that contain documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
publican package --desktop --binary --lang=cs-CZ: produces a desktop binary RPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.el5.noarch.rpm that contains documentation in Czech, built for the Red Hat Enterprise Linux 5 operating system.
publican package --desktop --short_sighted --lang=cs-CZ: produces a desktop SRPM package named Foomaster-Configuration_Guide-cs-CZ-2-6.src.rpm that contains documentation in Czech. This package will replace any Configuration Guides for previous versions of Foomaster that exists on a system. Users cannot have access to both the Foomaster 8 Configuration Guide and the Foomaster 9 Configuration Guide.

^[2] Refer to http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA