PUBLICAN(1)

📦

version 4.3.2 · 2 versions

4.3.2 · fedora 43 (latest)
4.3.2 · fedora 44

💖 PUBLICAN(1) 💖

okay bestie, welcome to publican — the User Contributed Perl Documentation one, aka the whole entire manual for the publican tool. grab a boba, we're doing this. 🧋✨

✨ NAME ✨

publican — a DocBook XML publishing tool. that's it, that's the vibe. it publishes things, DocBook XML things, and it slays while doing it. 👑

🌸 VERSION 🌸

This document describes publican version 4.0. yes, four point oh. iconic behavior.

🦋 SYNOPSIS 🦋

so here's how you talk to her:

publican <command options>

publican <action> <action options>

💅 Command Options

--help — Display help message. she'll tell you what's up.
--man — Display the man page. (you're literally reading it rn, hi 🙈)
--help_actions — Display a list of valid actions. the menu of options, fr fr.
-v — Display the version of Publican. little lowercase v, big knowledge.

👑 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 🫶

🌈 INTERFACE 🌈

bestie, this is the big one. every single action, every single flag, all of it. buckle up. 🎀

💜 add_revision

Add an entry to the revision history. like leaving a little note in the group chat but, y'know, for your book's version 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). this is THE moment, the main character action, the glow-up from XML to literally anything else. ✨

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.

bestie. real talk. do not use distributed_set on the command line. Publican uses it when it calls itself to process distributed sets, and that is the only safe way it can be used. respect the flag's boundaries. 🙈

🎀 clean

Remove all temporary files and directories. spring cleaning but make it terminal. 🧹✨

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. tidying up the IDs like a lil organizational queen. 💅

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. bye bestie, you're not local anymore. 😭

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. sharing is caring, no cap. 🫶

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. birthing a whole new piece of content, main character energy only. ✨

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. aesthetic time. 🎨

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. building your own little corner of the internet, obsessed. 💖

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. the config file got its own help text, she's that important. 💅

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

Installs a book into a WebSite. Yes bestie, it's literally what it says on the tin. 💖

Options:

--help — prints the help message, your lil safety net 🫶
--config=s — use a config file that isn't the standard one
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the Common_Content directory
--nocolours — turns OFF the ANSI colourisation of logging (so your terminal stays monochrome, boring but valid)
--quiet — kills all logging. silence. 🤫
--brand_dir=s — the directory to source brand files from
--site_config=<SITE_CONFIG> — the WebSite configuration file to use, or to create if it doesn't exist yet ✨
--lang=<LANG> — the language the XML will be written in

🎀 install_brand

Installs a brand to the location you hand it. Drop the brand off, no questions asked. 💅

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> — literally /path/to/install/to, the exact spot it goes 👑
--web — install the web content for a brand
--pub_dir=<PUB_DIR> — directory to publish files to. defaults to publish.

📊 lang_stats

Reports PO statistics, no cap. Numbers, counts, the whole tea. 🍓

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

Migrates a website DataBase from Publican < 3 to Publican 3. It's giving glow-up, it's giving era change. ✨

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

Packages a language for shipping. Wrapping it up cute so it can travel. 🎁

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 a desktop package instead of a web package
--brew — push the SRPM to brew 🍺
--scratch — use scratch instead of a tag build
--short_sighted — create the package without using the version in the package name
--binary — build a binary rpm when running package
--wait — wait for brew to finish building (patience era 🙈)
--pub_dir=<PUB_DIR> — directory to publish files to. defaults to publish.

🚫 print_banned

Prints a list of banned DocBook tags. The naughty list, fr fr. 💀

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

Prints a list of QA'd DocBook tags — the ones that already passed the vibe check. 🌈

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

Prints a tree of the xi:includes. Look at the branches bestie, they're so organized. 🌸

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

Prints a list of unused XML files. The ones nobody invited to the party. 😭

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

Prints a list of unused Image files. Same energy as above but for the pictures. 🎀

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

Removes a book from a WebSite. Un-inviting it, respectfully. 💔

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

Renames a publican book. New name, new era, same content. ✨

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

Prints a readability report for the source text. It's judging your sentences (lovingly). 👑

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

Reports on the contents of a WebSite. The whole site's stats, the receipts. 🧚

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

Snapshots the source language for use in translation. Literally a little photo of your text for the translators. 💖

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

Adds or removes database entries. Used for processing pre-build books, such as when building packages.

Options for this one 💅

--help — show the help message, like a little manual for the manual 🫶
--config=s — use a config file that is not the standard one
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the Common_Content directory
--nocolours — turn OFF the ANSI colourisation of logging (sad, but okay)
--quiet — disable all logging, silence era 🎀
--brand_dir=s — directory to source brand files from
--site_config=<SITE_CONFIG> — the 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. Translation upkeep, bestie, it's giving multilingual ✨

--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. The template files, the blueprint era, no cap 💖

--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 site's templates.

--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. Bringing the translations home, lowkey iconic 🫶

--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. Sending your translations out into the world, main character energy fr fr ✨

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

CONFIGURATION AND ENVIRONMENT 🌈

Publican needs access to wkhtmltopdf or Apache FOP if you wanna make PDF files. That's the vibe check for PDFs, bestie — no wkhtmltopdf, no FOP, no PDF, periodt 💀

DEPENDENCIES 👑

Here's the whole squad, the entire entourage, every single one of them:

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

Like… that's a LOT of friends and we love every single one of them 🥹💜

INCOMPATIBILITIES 💀

None reported. Zero drama. We're unproblematic, and that's on periodt ✋✨

BUGS AND LIMITATIONS 🐛

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

If you spot a bug, or you're just dying for a feature, please report it to publican-list@redhat.com, or through the web interface at <https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Publican&component=publican&version=$version>. We wanna hear it, bestie 🫶

AUTHOR 🎀

Jeff Fearn <jfearn@redhat.com> — icon, legend, the moment 👑

okay so that's the whole page, bestie, you made it to the end 🎉 and yeah, this was written for perl v5.42.0, dated 2025-07-25, and it's the PUBLICAN(1) manual — go forth and document, slay 💅💖✨

📦 where this page comes from

fedora 43: publican 4.3.2-33.fc43 · (GPL-2.0-or-later OR Artistic-1.0-Perl) AND CC0-1.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms