LOCALE:...BOOK.3PM(1)

📦
version 0.74 · 15 versions
, in alpine 3.23

✨ Locale::Po4a::Docbook(3pm) — the DocBook glow-up guide ✨

okay bestie, so this is a page from the perl man manual — LOCALE:...BOOK.3PM(1), from the User Contributed Perl Documentation crew 🫶 — and it's all about <pink>Locale::Po4a::Docbook</pink>. Let's get into it 💅

🌸 NAME 🌸

Locale::Po4a::Docbook — literally the module that converts DocBook XML documents from/to PO files. That's the whole vibe. ✨

🦋 DESCRIPTION 🦋

So the po4a (short for PO for anything) project's whole goal is to make translations easier — and even more importantly, to make maintaining those translations easier — by using gettext tools in places nobody expected them, like documentation. Iconic behaviour honestly 👑

Locale::Po4a::Docbook is the module that helps you translate DocBook XML documents into other [human] languages. Yes, human ones 💖

💀 STATUS OF THIS MODULE 💀

Good news: this module is fully functional, no cap — because it relies on the Locale::Po4a::Xml module to do the heavy lifting. This module itself only defines the translatable tags and attributes. Lowkey humble of it 🌈

The only known issue (the one thing that's giving 😭) is that it doesn't handle entities yet — and that includes the file inclusion entities. But here's the tea: you can translate most of those files alone (except the typical entities files), and it's usually better to maintain them separated anyway. Slay, separation of concerns 💅

🎀 OVERRIDE THE DEFAULT BEHAVIOR WITH COMMAND LINE OPTIONS 🎀

The default behavior of system provided modules is set to be on the safe side. Responsible queen behaviour fr fr 🫶

Here's the example: the default of the <author> tag aims for it to appear under <para>. But maybe you're using it only under <bookinfo> — main character placement, honestly. In that case, you may want to translate it independently for each author. Periodt.

So if you don't like the default behavior of the xml module and its derivative modules, you can provide command line options to change their behavior. For example, you can add the following to the po4a configuration file:

opt:"-k 0 -o nodefault=\"<bookinfo> <author>\" \
          -o break=\"<bookinfo> <author>\" \
          -o untranslated=\"<bookinfo>\" \
          -o translated=\"<author>\""

So what does this actually do? It overrides the default behavior for <bookinfo> and <author>, sets <bookinfo> and <author> to break the input data stream on these tags, sets <bookinfo> not to translate its tagged content, and sets <author> to translate its tagged content. Chef's kiss configuration 🔥

🧚 SEE ALSO 🧚

Go read them, iykyk 📚✨

👑 AUTHORS 👑

  • Jordi Vilalta <jvprat@gmail.com>
  • Copyright © 2004 Jordi Vilalta <jvprat@gmail.com>
  • Copyright © 2007-2009 Nicolas François <nicolas.francois@centraliens.net>

This program is free software; you may redistribute it and/or modify it under the terms of GPL v2.0 or later (see the COPYING file). Respect the license bestie, it's not optional 💅

ngl the "no entities yet" thing is the one little caveat to keep in your pocket — everything else here is fully functional and living its best life 🌸

and that's the whole page, bestie! This one came from perl v5.42.0, dated 2025-07-13 🎀 — go forth and translate some DocBook, you've got this 💖✨🦋

📦 where this page comes from