PUBLICAN(1p)

📦

version 4.3.2 · 5 versions

4.3.2 · debian bookworm, ubuntu jammy (latest)
4.3.2 · ubuntu stonking
4.3.2 · ubuntu noble
4.3.2 · ubuntu resolute
4.3.2 · debian trixie, ubuntu questing

💖 PUBLICAN 💖

okay bestie, sit down, hydrate, because we're about to talk about publican — a DocBook XML publishing tool. that's the whole NAME section, no cap. it's publican(1p), from the User Contributed Perl Documentation crew. slay.

✨ VERSION ✨

so like, this document describes publican version 4.0. she's grown, she's evolved 💅

🌈 SYNOPSIS 🌈

here's how you actually call her:

publican <command options>

publican <action> <action options>

🎀 Command Options 🎀

these are the big-picture flags, the ones that apply at the top level, periodt:

--help — shows you the help message 🫶
--man — shows you the man page (hi, that's this 💖)
--help_actions — lists out all the valid actions for you
-v — shows you the version of Publican

🦋 Valid actions are: 🦋

here's the full roster, no gatekeeping:

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.

and if you're lost, run this lil baby:

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

iykyk 💅

🌸 INTERFACE 🌸

this is the big one, bestie. every action, every flag, laid out. grab a snack 🍓

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

🚨 real talk bestie — do NOT put distributed_set on the command line. that's not the vibe. Publican uses it internally when it calls itself to process distributed sets, and that's the only safe way it can be used. respect the flag, fr fr 💀

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

okay we're not done yet bestie, there's more where that came from 💖

`install_book` 📚💖

Install a book in to a WebSite. Basically you've got a book, you've got a website, and this is the lil' matchmaker that gets them together. slay

Options ✨

--help — shows you the help message, bestie 🫶
--config=s — points at a config file that isn't the standard one
--common_config=s — overrides the path to the Common_Config directory
--common_content=s — overrides the path to the Common_Content directory
--nocolours — kills the ANSI colourisation of logging
--quiet — kills all the logging, every last bit of it
--brand_dir=s — the directory you're sourcing brand files from
--site_config=<SITE_CONFIG> — the 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 — you tell it where, it goes there. no cap.

Options ✨

--help — display the help message 💅
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — the numbers, the vibes, the translation tea. 🍓

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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. glow-up time for your old database, fr fr.

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — wrap it up, it's going on a trip.

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 ⏳
--pub_dir=<PUB_DIR> — directory to publish files to. Defaults to publish.

`print_banned` 🚫

Print a list of banned DocBook tags — the tags that are, like, so not allowed here.

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — the tags that did pass the vibe check. 💅

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — your whole include structure, branching out like the main character it is.

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — all the files just sitting there, not being included by anyone. it's giving neglected. 😭

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — same energy as above but for your pictures. the abandoned gallery. 🎀

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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. — okay so this one does the opposite of install_book. it's the breakup. 😭

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — new name, who dis? 🦋

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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. — it reads your writing and tells you how it reads. meta, lowkey. ⭐

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — the full rundown on what's living in your site. 💜

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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. — freeze frame on the source language so the translators can do their thing. 📸

Options ✨

--help — display the help message
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the 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 — shows you the help message, like a little map 🗺️
--config=s — use a nonstandard config file
--common_config=s — override the path to the Common_Config directory
--common_content=s — override the path to the Common_Content directory
--nocolours — disable ANSI colourisation of logging (so no rainbow logs 😭)
--quiet — disable all logging (shhh 🤫)
--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.

⚙️ CONFIGURATION AND ENVIRONMENT ⚙️

Publican requires access to wkhtmltopdf or Apache FOP for creating PDF files. Like, if you want PDFs, you gotta have one of these, bestie. No cap. 💅

📦 DEPENDENCIES 📦

You need all these modules, periodt. Here's the whole squad:

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

🚫 INCOMPATIBILITIES 🚫

None reported. So like, no drama? 🕊️

🐛 BUGS AND LIMITATIONS 🐛

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

Please report any bugs or feature requests 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>.

👑 AUTHOR 👑

Jeff Fearn <jfearn@redhat.com> — iconic, periodt. 💖

And that's the whole vibe, bestie. This page is from perl v5.26.2, dated 2018-07-08, and it's PUBLICAN(1p). Stay slaying with your docs! 💅✨

📦 where this page comes from

debian bookworm: publican 4.3.2-3 · Artistic-1.0-Perl OR GPL-2.0-or-later
ubuntu jammy: publican 4.3.2-3 · Artistic-1.0-Perl OR GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms

PUBLICAN(1p)

💖 PUBLICAN 💖

✨ VERSION ✨

🌈 SYNOPSIS 🌈

🎀 Command Options 🎀

🦋 Valid actions are: 🦋

🌸 INTERFACE 🌸

🧚 add_revision

🔥 build

🎀 clean

✨ clean_ids

🦋 clean_set

💜 copy_web_brand

👑 create

🌈 create_brand

🫶 create_site

🍓 help_config

install_book 📚💖

install_brand 🎀

lang_stats 📊

migrate_site 🧚

package 📦🔥

print_banned 🚫

print_known 👑

print_tree 🌳

print_unused 🙈

print_unused_images 🖼️

remove_book 💀

rename ✏️

report 📝

site_stats 📈

trans_drop 🌸

update_db 🗄️

update_po

update_pot

update_site

zt_pull

zt_push

⚙️ CONFIGURATION AND ENVIRONMENT ⚙️

📦 DEPENDENCIES 📦

🚫 INCOMPATIBILITIES 🚫

🐛 BUGS AND LIMITATIONS 🐛

👑 AUTHOR 👑

`install_book` 📚💖

`install_brand` 🎀

`lang_stats` 📊

`migrate_site` 🧚

`package` 📦🔥

`print_banned` 🚫

`print_known` 👑

`print_tree` 🌳

`print_unused` 🙈

`print_unused_images` 🖼️

`remove_book` 💀

`rename` ✏️

`report` 📝

`site_stats` 📈

`trans_drop` 🌸

`update_db` 🗄️