Chapter 3. Publican commands

3.1. Command options
3.2. Actions

Publican is a command-line tool. To use Publican on a computer with a Linux operating system, you must either start a terminal emulator program (such as GNOME Terminal or Konsole) or switch to a virtual console. To use Publican on a computer with a Windows operating system, run the $ cmd command from the Start menu to open a command prompt.

Publican commands take one of the following formats:

$ publican command_option: The command_option is any of several options for the $ publican command itself.
$ publican action action_options: The action is an action for Publican to perform, such as creating the XML files for a new document or building a HTML document from a document's XML files. The action_options apply to the action, such as specifying the language of a document.
$ publican command_option action action_options: Some command_options affect the output of actions, for example, whether Publican should use ANSI colors in its output.

3.1. Command options

The options for the $ publican command are:

--help: This option displays a help message, a condensed version of the contents of this chapter.
--man: This option displays the man page for Publican, which includes the same information as the --help option supplies, in addition to information about licensing and dependencies.
--help_actions: This option displays a list of valid Publican actions.
-v: This option displays the version number of your Publican installation.
--config file: This option allows you to specify a config file for a document, in place of the default publican.cfg.
--nocolours: This option disables ANSI colors in Publican logging.
--quiet: This option disables all logging.

3.2. Actions

Publican can perform the following actions:

add_revision: adds an entry in Revision_History.xml.
build: transforms XML to other formats (for example: PDF, single-page HTML, or multiple-page HTML). Refer to Section 4.7, “Building a document” for more details and a description of the available options.
clean: removes all files and folders in the tmp/ subdirectory. The tmp/ subdirectory is created after running the $ publican build command to build a document, such as publican build --formats=html --langs=en-US.
clean_ids: changes all IDs to a standard format. This format is Book_Name-title. For example, a section with a title of First Section in a book named Test_Book will have the following ID after you run $ publican clean_ids: <section id="Test_Book-First_Section">
Warning — $ publican clean_ids
To make translation easier, $ publican clean_ids uses the first four characters of the tag as a prefix for the ID. Consequently, you must check out the latest versions of the XML source and translations before running this command.
If you do not have the current versions of the PO files checked out before running $ publican clean_ids, the XML and PO files will no longer be in synchrony with each other. In this case, all links in the PO files must be manually updated.
Important — ID conflicts can occur
The $ publican clean_ids command is intended to facilitate building a DocBook structure around documents ported from other formats such as HTML. However, publican clean_ids is file-based and and only has access to information in the XML file that it is currently processing and to the document name. Therefore, nodes of the same type that have the same title receive the same IDs. These duplicate IDs will prevent the document from building.
Use the $ publican clean_ids command to assist you in laying out your document, but expect that some manual adjustment to IDs might be necessary. We recommend that you do not run publican clean_ids on an already well established document.
clean_set: removes local copies of remote books in a distributed set. Refer to Section 6.2, “Distributed sets” for details of using distributed sets.
create: creates a new book, article, or set. Refer to Chapter 4, Creating a document for details of creating a book or article, and to Chapter 6, Using sets for details of using sets.
create_brand: creates a new brand. Refer to Section 5.2, “Creating a brand” for details of creating a brand.
create_site: creates a documentation website. Refer to Chapter 7, Building a website with Publican for details.
help_config: displays help text for the configuration file contained in each book or brand, publican.cfg. Refer to Section 4.1.1, “The publican.cfg file” for more detail.
install_book: installs a document on a documentation website. Refer to Chapter 7, Building a website with Publican for details.
install_brand: configures a brand for installation. Refer to Section 5.1, “Installing a brand” for details of installing a brand.
lang_stats --lang=language_code: generates a translation report for the language specified by language_code. For every PO file generated by Publican, a table displays the number of untranslated strings in all msgids; the number of fuzzy strings (counts the strings contained in msgids whose content changed since the last POT generation) and the number of translated strings, coinciding after translation, with the the number of strings contained in the msgid.
migrate_site: migrates a website database from Publican 2.x to Publican 3.
package: packages a book, article, set, or brand for shipping as an RPM package. Refer to Section 4.8, “Packaging a document” and Section 5.4, “Packaging a brand” for more detail.
print_banned: prints a list of DocBook tags banned by Publican. Refer to Appendix A, Disallowed elements and attributes for a discussion of banned tags.
print_known: prints a list of DocBook tags supported by Publican. Supported are those tags whose output has undergone at least cursory verification for quality when used in Publican — refer to Appendix A, Disallowed elements and attributes.
print_tree: prints a tree of the XML files included with the <xi:include> tag in a book, article, or set.
print_unused: prints a list of the XML files not included with the <xi:include> tag in a book, article, or set.
publican print_unused_images: prints a list of the image files not referenced by an <imagedata> tag in a book, article, or set.
remove_book: removes a document from a documentation website. Refer to Chapter 7, Building a website with Publican for details.
rename: renames a Publican book.
site_stats: generates a site report for a documentation website.
update_po: updates the portable object (PO) files. Refer to Section 4.6, “Preparing a document for translation” for more detail.
update_pot: updates the portable object template (POT) files. Refer to Section 4.6, “Preparing a document for translation” for more detail.
update_site: updates the templated content of the documentation website. Refer to Chapter 7, Building a website with Publican for details.