=head1 NAME

publican - a DocBook XML publishing tool.

=head1 VERSION

This document describes publican version 4.0

=head1 SYNOPSIS

publican <command options>

publican <action> <action options>

Command Options

    --help 		Display help message
    --man		Display the man page
    --help_actions	Display a list of valid actions
    -v			Display the version of Publican

Valid actions are:

    add_revision  Add an entry to the revision history
    build         Transform XML to other formats (pdf, html, html-single, drupal-book, etc)
    clean         Remove all temporary files and directories
    clean_ids     Run clean ids for source XML
    clean_set     Remove local copies of remote set books
    copy_web_brand  Copy a brand's installed web content to another site
    create        Create a new book, set, or article
    create_brand  Create a new brand
    create_site   Create a new WebSite in the supplied location.
    help_config   Display help text for the configuration file
    install_book  Install a book in to a WebSite.
    install_brand  Install a brand to the supplied location
    lang_stats    report PO statistics
    migrate_site  Migrate a website DataBase from Publican < 3 to Publican 3.
    package       Package a language for shipping
    print_banned  Print a list of banned DocBook tags
    print_known   Print a list of QA'd DocBook tags
    print_tree    Print a tree of the xi:includes
    print_unused  Print a list of unused XML files
    print_unused_images  Print a list of unused Image files
    remove_book   Remove a book from a WebSite.
    rename        Rename a publican book
    report        Print a readability report for the source text.
    site_stats    Report on the contents of a WebSite
    trans_drop    Snapshot the source language for use in translation.
    update_db     Add or remove database entries. Used for processing pre-build books, such as when building packages.
    update_po     Update the PO files
    update_pot    Update the POT files
    update_site   Update an existing sites templates.
    zt_pull       Pull translations from Zanata.
    zt_push       Push translations to Zanata.


Run: 'bin/publican <action> --help' for details on action usage

=head1 INTERFACE 

add_revision
    Add an entry to the revision history

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --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.


build
    Transform XML to other formats (pdf, html, html-single, drupal-book, etc)

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --formats=<FORMATS>       Comma-separated list of formats, for example: html,pdf,html-single,html-desktop,txt,epub
        --langs=<LANGS>           Comma-separated list of languages, for example: en-US,de-DE,all
        --publish                 Set up built content for publishing
        --embedtoc                Embed the web site TOC object in the generated HTML
        --distributed_set         This flag tells publican the data being processed is a distributed set. Note: do not use distributed_set on the command line. Publican uses this flag when calling itself to process distributed sets. This is the only safe way this flag can be used.
        --novalid                 Do not run the DTD validation
        --src_dir=<SRC_DIR>       Directory to source publican files from.
        --pdftool=<PDFTOOL>       Override the tool to use when creating PDFs. Valid options are wkhtmltopdf and fop.
        --pub_dir=<PUB_DIR>       Directory to publish files to. Defaults to publish.


clean
    Remove all temporary files and directories

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --pub_dir=<PUB_DIR>       Directory to publish files to. Defaults to publish.


clean_ids
    Run clean ids for source XML

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


clean_set
    Remove local copies of remote set books

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


copy_web_brand
    Copy a brand's installed web content to another site

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --brand=<BRAND>           The brand to use
        --site_config=<SITE_CONFIG>    WebSite configuration file to use or create.
        --old_site_config=<OLD_SITE_CONFIG>    WebSite configuration file to use when copying content between sites.


create
    Create a new book, set, or article

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --name=<NAME>             The name of the book, article, set, or brand
        --version=<VERSION>       The version of the product
        --edition=<EDITION>       The edition of the book, article, or set
        --product=<PRODUCT>       The name of the product
        --brand=<BRAND>           The brand to use
        --lang=<LANG>             The language the XML will be written in
        --type=<TYPE>             The type (book, article, or set)
        --dtdver=<DTDVER>         The version of the DocBook DTD to use


create_brand
    Create a new brand

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --name=<NAME>             The name of the book, article, set, or brand
        --lang=<LANG>             The language the XML will be written in


create_site
    Create a new WebSite in the supplied location.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --site_config=<SITE_CONFIG>    WebSite configuration file to use or create.
        --db_file=<DB_FILE>       Override default database file.
        --toc_path=<TOC_PATH>     Override the default TOC path.
        --tmpl_path=<TMPL_PATH>    Override the default template path.
        --lang=<LANG>             The language the XML will be written in


help_config
    Display help text for the configuration file

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


install_book
    Install a book in to a WebSite.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --site_config=<SITE_CONFIG>    WebSite configuration file to use or create.
        --lang=<LANG>             The language the XML will be written in


install_brand
    Install a brand to the supplied location

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --path=<PATH>             /path/to/install/to
        --web                     Install the web content for a brand.
        --pub_dir=<PUB_DIR>       Directory to publish files to. Defaults to publish.


lang_stats
    report PO statistics

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --lang=<LANG>             The language the XML will be written in


migrate_site
    Migrate a website DataBase from Publican < 3 to Publican 3.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --site_config=<SITE_CONFIG>    WebSite configuration file to use or create.


package
    Package a language for shipping

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --lang=<LANG>             The language the XML will be written in
        --desktop                 Create desktop instead of web package
        --brew                    Push SRPM to brew
        --scratch                 Use scratch instead of tag build
        --short_sighted           Create package without using version in package name
        --binary                  Build binary rpm when running package
        --wait                    Wait for brew to finish building
        --pub_dir=<PUB_DIR>       Directory to publish files to. Defaults to publish.


print_banned
    Print a list of banned DocBook tags

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


print_known
    Print a list of QA'd DocBook tags

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


print_tree
    Print a tree of the xi:includes

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


print_unused
    Print a list of unused XML files

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


print_unused_images
    Print a list of unused Image files

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


remove_book
    Remove a book from a WebSite.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --site_config=<SITE_CONFIG>    WebSite configuration file to use or create.
        --lang=<LANG>             The language the XML will be written in


rename
    Rename a publican book

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --name=<NAME>             The name of the book, article, set, or brand
        --product=<PRODUCT>       The name of the product
        --version=<VERSION>       The version of the product


report
    Print a readability report for the source text.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


site_stats
    Report on the contents of a WebSite

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --site_config=<SITE_CONFIG>    WebSite configuration file to use or create.


trans_drop
    Snapshot the source language for use in translation.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


update_db
    Add or remove database entries. Used for processing pre-build books, such as when building packages.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --site_config=<SITE_CONFIG>    WebSite configuration file to use or create.
        --add                     Add a database entry
        --del                     Delete a database entry
        --lang=<LANG>             The language the XML will be written in
        --product=<PRODUCT>       The name of the product
        --version=<VERSION>       The version of the product
        --name=<NAME>             The name of the book, article, set, or brand
        --formats=<FORMATS>       Comma-separated list of formats, for example: html,pdf,html-single,html-desktop,txt,epub
        --subtitle=<SUBTITLE>     Sub title for a book
        --abstract=<ABSTRACT>     Abstract for a book
        --product_label=<PRODUCT_LABEL>    product label for a book
        --version_label=<VERSION_LABEL>    version label for a book
        --name_label=<NAME_LABEL>    name label for a book
        --sort_order=<SORT_ORDER>    Order to sort a book
        --book_version=<BOOK_VERSION>    The version number of the book being installed.
        --book_src_lang=<BOOK_SRC_LANG>    The language this translation is based on.


update_po
    Update the PO files

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --langs=<LANGS>           Comma-separated list of languages, for example: en-US,de-DE,all
        --msgmerge                Use gettext's msgmerge for POT/PO merging.
        --firstname=<FIRSTNAME>    firstname to use for a revision.
        --surname=<SURNAME>       surname to use for a revision.
        --email=<EMAIL>           email to use for a revision.
        --previous                Keep previous msgid when fuzzy matches are detected in PO updates.


update_pot
    Update the POT files

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


update_site
    Update an existing sites templates.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.
        --site_config=<SITE_CONFIG>    WebSite configuration file to use or create.


zt_pull
    Pull translations from Zanata.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.


zt_push
    Push translations to Zanata.

	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 colourisation of logging.
        --quiet                   Disable all logging.
        --brand_dir=s             Directory to source brand files from.




=head1 CONFIGURATION AND ENVIRONMENT

Publican requires access to wkhtmltopdf or Apache FOP for creating PDF files.

=head1 DEPENDENCIES

Archive::Tar
Archive::Zip
Carp
Config::Simple
Cwd
DBI
DateTime
DateTime::Format::DateParse
Devel::Cover
Encode
File::Basename
File::Copy::Recursive
File::Find
File::Find::Rule
File::HomeDir
File::Inplace
File::Path
File::Spec
File::Which
File::pushd
Getopt::Long
HTML::FormatText
HTML::FormatText::WithLinks
HTML::FormatText::WithLinks::AndTables
HTML::TreeBuilder
I18N::LangTags::List
IO::String
Lingua::EN::Fathom
List::MoreUtils
List::Util
Locale::Language
Locale::Maketext::Gettext
Locale::Maketext::Lexicon
Locale::Msgfmt
Locale::PO
Module::Build
Pod::Usage
Sort::Versions
String::Similarity
Syntax::Highlight::Engine::Kate
Template
Template::Constants
Term::ANSIColor
Test::More
Test::Pod
Test::Pod::Coverage
Text::CSV_XS
Text::Wrap
Time::localtime
XML::LibXML
XML::LibXSLT
XML::Simple
XML::TreeBuilder
version

=head1 INCOMPATIBILITIES

None reported.

=head1 BUGS AND LIMITATIONS

Bug list at L<https://bugzilla.redhat.com/buglist.cgi?product=Publican&query_format=advanced&resolution=--->.

Please report any bugs or feature requests to
C<publican-list@redhat.com>, or through the web interface at
L<https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Publican&component=publican&version=$version>.

=head1 AUTHOR

Jeff Fearn  C<< <jfearn@redhat.com> >>
=cut
