- Prev
- Users' Guide
- Next

# Chapter 3. Publican commands

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 `msgid`s; the number of fuzzy strings (counts the strings contained in `msgid`s 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.

- PrevChapter 2. Publican defaults
- Up
- Home
- NextChapter 4. Creating a document