# 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 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).

## 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