⁠Appendix B. Command summary

⁠

Command options

$ publican --help: displays help
$ publican --man: displays the manual page
$ publican --help_actions: displays a list of actions
$ publican --v: displays the Publican version number.
--config file: specifies a config file for a document, in place of the default publican.cfg.
--nocolours: disables ANSI colors in Publican logging.
--quiet: disables all logging.

⁠

Actions

$ publican add_revision

adds an entry in Revision_History.xml. Options:

--lang=LANG: the language the XML will be written in.
--revnumber=REVNUMBER: revision number to use for a revision.
--date=DATE: date to use for a revision.
--member=MEMBER: an entry to be added to the revision. Can be specified multiple times.
--firstname=FIRSTNAME: firstname to use for a revision.
--surname=SURNAME: surname to use for a revision.
--email=EMAIL: email to use for a revision.

$ publican build

transforms XML into a document. Options:

--help: display help message.
--config=s: use a nonstandard config file.
--common_config=s: override path to Common_Config directory.
--common_content=s: override path to Common_Content directory.
--nocolours: disable ANSI colorization of logging.
--quiet: disable all logging.
--brand_dir=s: directory to source brand files from.
--formats=FORMATS: comma-separated list of formats to build. For example: html,pdf,html-single,html-desktop,txt,epub (mandatory).
--langs=LANGS: comma-separated list of languages to build. For example: en-US,de-DE,all (mandatory).
--publish: sets up built content for publishing.
--embedtoc: embeds a table of contents into HTML output.
--novalid: skips DTD validation when building a document.
--src_dir=SRC_DIR: specifies the directory to source Publican files from.
--pdftool=s: Override the tool to use when creating PDFs. Valid options are wkhtmltopdf and fop.
--pub_dir=PUB_DIR: Override the directory to publish files to. Defaults to 'publish'.

$ publican clean

removes the temporary directories from a document directory.

$ publican clean_ids

indents XML files neatly, and rebuilds element IDs.

$ publican clean_set

removes local copies of remote books that are part of a set.

$ publican create

creates a new book, article, or set. Options:

--name: the name of the document (mandatory).
--product: the documented product.
--version: the version of the documented product.
--edition: the edition of the document.
--brand: the brand for the document.
--lang: the language in which the XML will be authored.
--type: the type of document — article, book, or set.

$ publican create_brand

creates a new brand. Options:

--name: the name of the document (mandatory).
--lang: the language in which the XML will be authored.

publican create_site

creates a documentation website. Options:

--site_config: name of the site configuration file to create (mandatory).
--db_file: name of the site database file to create (mandatory).
--toc_path: path to the directory in which to create the top-level toc.html file (mandatory).
--tmpl_path: path to the template directory (by default, /usr/share/publican/templates).

$ publican help_config

displays a list of parameters for the publican.cfg file.

publican install_book

installs a document on a documentation website.

--site_config: name of the site configuration file (mandatory).
--lang: the language of the document to install (mandatory).

$ publican install_brand

configures a brand for installation. Option:

--path: path to the Publican Common Content files. By default, /usr/share/publican/Common_Content on Linux operating systems and at %SystemDrive%/%ProgramFiles%/Publican/Common_Content on Windows operating systems — typically, C:/Program Files/Publican/Common_Content

$ publican copy_web_brand

copy a brand's installed web content to another site. Options:

--brand: the brand to copy.
--old_site_config=site_config: website configuration file to copy brand web content from.
--site_config=site_config: website configuration file to copy brand web content to.

$ publican lang_stats

generates a translation report for a language.

--langs: a comma-separated list of languages for which the report will be generated.

$ publican migrate_site

migrates a website database from Publican 2.x to Publican 3. Options:

--site_config=site_config: website configuration file to use or create.

$ publican package

packages a document or brand for distribution. Options:

--lang: the language to package (mandatory for documents, meaningless for brands).

--desktop: specifies that a document RPM package should be built for desktop use (meaningless for brands).

--brew: pushes a package to the Brew build system (meaningless outside Red Hat).

--scratch: used in conjunction with --brew to specify a scratch build (meaningless outside Red Hat).

--short_sighted: builds the package without the product version number in the package name.

--binary: builds the package as a binary RPM package rather than a source RPM package.

publican print_banned

prints a list of DocBook tags banned by Publican.

publican print_known

prints a list of DocBook tags supported by Publican.

$ publican print_tree

displays a tree of the XML files included in a document.

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

publican remove_book

removes a document from a documentation website.

--site_config: name of the site configuration file (mandatory).
--lang: the language of the document to remove (mandatory).

$ publican rename

renames a document. Options:

--name: the new title for the document.
--product: the new product to which the document applies.
--version: the new product version to which the document applies.

publican site_stats --site_config=name_of_site_config_file

generates a site report for a documentation website. Option:

--site_config: name of the site configuration file (mandatory).

$ publican update_pot

updates the POT files in a document.

$ publican update_po

updates the PO files in a document.

--langs: comma-separated list of languages to update, or ‘all’ to update all (mandatory).
--msgmerge: use gettext's msgmerge for POT/PO merging.

publican update_site --site_config=name_of_site_config_file.cfg

regenerates the templated content of a documentation website. Option:

--site_config: name of the site configuration file (mandatory).

⁠B.1. Internal commands

Publican uses the commands documented in this section internally. There is normally no need to run them manually.

publican update_db --add

Adds entries to the database of a Publican-generated website, with the following options:

--site_config: name of the site configuration file.
--lang: the language in which the document is published.
--formats: a comma-separated list of the formats in which the document is published, for example, pdf,html-single
--name: the title of the document.
--name_label: the title of the document, as it should appear in the site's tables of contents.
--product: the product that the document describes.
--product_label: the product that the document describes, as it should appear in the site's tables of contents.
--version: the version of the product that the document describes.
--version_label: the version of the product that the document describes, as it should appear in the site's tables of contents.
--subtitle: the subtitle of the document.
--abstract: the abstract of the document.

For example:

publican update_db --add --lang en-US --formats html,pdf --name Foo \
--name_label "foo is good" --version 0.1 --version_label UNUSED \
--product Bar --product_label "To the bar" \
--subtitle "A guide to Bar Foo" \
--abstract "There once was a Foo from Bar ..." \
--site_config /usr/share/bar/foo.cfg

publican update_db --del

removes entries from the database of a Publican-generated website, with the following options:

--site_config: name of the site configuration file.
--lang: the language in which the document is published.
--name: the title of the document.
--product: the product that the document describes.
--version: the version of the product that the document describes.

For example:

publican update_db --del --lang en-US --name Foo --version 0.1 --product Bar \
--site_config /usr/share/bar/foo.cfg