8. Packaging a document

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.

Note — Customizing output

The parameters set in the document configuration file (by default, publican.cfg) allow you to control many aspects of the way in which a document is presented and packaged — refer to Section 1.1, “The publican.cfg file”.

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 --config to specify which configuration file (and therefore which set of parameters) to use in a particular build, for example: 

$ publican package --lang hi-IN --config community.cfg

Publican not only builds documentation, but it can package built content 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.

8.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.

8.1.1. Source RPM packages and binary RPM packages

SRPM packages contain 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 and a spec file rather than finished documents in formats such as HTML and PDF. You cannot install documentation directly from SRPM packages with current versions of the RPM Package Manager.

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 Publican installed. Installing Publican-generated documentation on a webserver does requires Publican to be installed, but for reasons other than compiling the source code. Refer to Section 8.1.2, “Desktop packages and web packages” for a description of the differences between documentation installed for local use (desktop RPMs) and documentation installed to serve as web content (web RPMs).

8.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 (binary) 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’.[3] The desktop RPM package also contains a desktop file, to be placed in /usr/share/applications/. This file enables desktop environments to add the installed document to their menus for ease of reference by users. By default, the menu item appears under System → Documentation on the GNOME desktop. To customize the placement of the menu item, create a documentation menu package to supply .directory and .menu files and set the dt_requires and menu_category parameters in the publican.cfg file to require this package and supply the appropriate menu category. Refer to Section 8.1.3, “Desktop menu entries for documents”

By default, web RPM packages of Publican documents contain the documentation in single-page HTML, multi-page HTML, EPUB, and PDF formats. The formats included vary if:

  • you publish documentation in a language in which PDF output is not currently supported. Publican relies on FOP to generate PDF output. FOP does not presently support right-to-left text (for example, Arabic, Persian, or Hebrew). Furthermore, because FOP cannot presently specify fonts on a character-by-character basis, a lack of available fonts in Indic scripts that also include Latin glyphs prevents Publican from reliably generating PDF output in Indic languages. By default, Publican does not include PDF files in web RPM packages generated in Arabic, Persian, Hebrew, or any Indic language.

  • your book or your brand contains the web_formats parameter. The value of this parameter overrides the default formats that Publican packages. For example, to publish the document only as single-page HTML, PDF, and text, set web_formats: "html-single,pdf,txt"

Built content is installed in subdirectories 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.

8.1.3. Desktop menu entries for documents

By default, RPM packages of Publican documents for desktop use appear on the GNOME desktop under the System → Documentation menu. When users have large numbers of documents installed on their systems, this menu becomes very cluttered and difficult to navigate. Documentation for many different products and perhaps different languages becomes intermixed, adding to the confusion.

To group documentation for your product under a separate submenu within the GNOME System → Documentation menu, you must:

  • create and distribute a desktop menu package that creates the new submenu.

  • specify the menu category in the document, and optionally, have the documentation package require the desktop menu package.

Note that the Documentation menu does not group entries under a submenu until two or more documents are installed that belong on that submenu. The first document appears under System → Documentation.

8.1.3.1. Creating an desktop menu package

A desktop menu package consists of:

  • a desktop entry (.directory) file that provides metadata about the new submenu.

  • a desktop menu (.menu) file that defines the position of the new submenu within the Documentation menu.

The structure for the .directory file for Publican-generated documentation is as follows:

  • the group header [Desktop Entry]

  • the Name parameter, set to the name of the submenu that you want to place under the Documentation menu.

  • optionally, localizations of the Name parameter, in the format Name[language_code] where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.

  • the Comment parameter, set to a description of the new submenu.

  • optionally, localizations of the Comment parameter, in the format Comment[language_code] where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.

  • the Type parameter, set to Directory.

  • the Encoding parameter, set to UTF-8.

Example 4.5. Example .directory file

The following file, menu-example.directory illustrates the structure of a desktop entry file. 

[Desktop Entry]
Name=Example
Name[fr]=Exemple
Name[it]=Esempio
Comment=Example Documentation menu
Comment[fr]=Exemple d'une menu de documentation
Comment[it]=Esempio di un menù di documentazione
Type=Directory
Encoding=UTF-8

The desktop entry file is placed in /usr/share/desktop-directories/

For a full description of how desktop entries work, refer to the Desktop Entry Specification, available from http://standards.freedesktop.org/entry-spec/latest/

A desktop menu file is an XML file that contains:

  • a document type declaration for the freedesktop.org Desktop Menu Specification: 

    <!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
"http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">

  • a root element, <Menu>, that contains:

    • a <Name> element with the content Documentation

    • another <Menu> element that in turn contains:

      • a <Name> element with the content Documentation (just like the root element)

      • a <Directory> element with its content the name of the desktop entry file you created, for example: 

        <Directory>menu-example.directory</Directory>

      • an <Includes> element with the content X-category_name, where category_name is an identifier for the documents that will be grouped together under this menu entry. For example: 

        <Includes>X-Example-Docs</Includes>

Example 4.6. Example .menu file

The following file, menu-example.menu illustrates the structure of a desktop menu file. 

<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
<Menu>
	<Name>Documentation</Name>
	<Menu>
		<Name>Documentation</Name>
		<Menu>
			<Name>Example</Name>
			<Directory>menu-example.directory</Directory>
			<Include>
				<Category>X-Example-Docs</Category>
			</Include>
		</Menu>
	</Menu> 
</Menu>

The desktop menu file is placed in /etc/xdg/menus/settings-merged/

For a full description of how desktop menus work, refer to the Desktop Menu Specification, available from http://standards.freedesktop.org/desktop-menu-spec/latest/

8.1.3.2. Setting a desktop menu category

To place a document in a submenu of System → Documentation, set the menu_category parameter in its publican.cfg file to match the content of the <Includes> element in the corresponding desktop menu file. For example, consider a desktop menu file that contains the element: 

<Includes>X-Example-Docs</Includes>

To place a document in the submenu defined by this desktop menu file, the document's publican.cfg file should contain: 

menu_category: X-Example-Docs
Important

Publican will process the string in menu_category and replace __LANG__ with the current language. This allows menus to be customized on a per language basis. 

menu_category: X-Example-Docs-__LANG__

Note that you can include this parameter in the defaults.cfg file or overrides.cfg file of a brand so that all documents built with that brand are grouped into this submenu automatically without you having to set the menu_category parameter in each document.

If you ship the desktop menu and desktop entry files in an RPM package, you can make RPM packages of documentation require the desktop menu package. With this dependency set, the desktop menu package is installed automatically on users' systems when they install a documentation package, which ensures that the documentation appears under the submenu you have created for your project. Set the dependency with the dt_requires parameter in the document's publican.cfg file. For example, if you ship a desktop menu package named foodocs-menu, set: 

dt_requires: foodocs-menu

Note that you can include this parameter in the defaults.cfg file or overrides.cfg file of a brand so that all documents built with that brand require the same desktop menu package.

8.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 F, 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 language

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.

--config filename

specifies that Publican should use a configuration file other than the default publican.cfg file.

--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 an 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 configuration file (by default, publican.cfg) to supply the various parameters in the file name, and then information in the Book_Info.xml file for any parameters missing from the configuration file. Refer to Section 1, “Files in the book directory” for details of the parameters used in these files. Additionally, note that:

  • 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.

  • packages of translated documents take their release numbers from the Project-Id-Version parameter in the Article_Info.po or Book_Info.po 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.

8.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 XML source files in Czech, together with a spec file.

$ publican package --desktop --lang=cs-CZ

produces a desktop SRPM package named Foomaster-Configuration_Guide-9-cs-CZ-2-6.src.rpm that contains XML source files in Czech, together with a spec file.

$ 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.