Product SiteDocumentation Site

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