DOCBOOK2MDOC(1)

💖 DOCBOOK2MDOC(1) — the general commands manual, bestie ✨

okay so real talk, this is docbook2mdoc from section 1 of the General Commands Manual, and it's literally the glow-up machine that turns your DocBook into pretty mdoc. sit down, grab a lil drink 🍓, we're doing this.

---

✨ NAME ✨

docbook2mdoc — convert DocBook to mdoc 💅

---

🦋 SYNOPSIS 🦋

docbook2mdoc [-W] [-s section] [-T mdoc | tree | lint] [file]

---

🌸 DESCRIPTION 🌸

So the docbook2mdoc utility reads DocBook input from a file and translates it to mdoc(7) and eqn(7). iconic behaviour, no notes. if file is omitted, standard input gets used instead — she's flexible like that 🫶

The options are as follows, pls pay attention:

• -s — Specify the manual page section to be used as the second argument of the Dt macro. Defaults to the content of the first <manvolnum > element in the first <refmeta > block, if any, or to "1" otherwise. so if you don't tell her, she'll snoop for it herself 👑
• -T — Select the output mode. The following arguments are supported:
  • mdoc — Translate the input to mdoc(7). This is the default. the classic, the moment, the main character 🌈
  • tree — Dump a human-readable representation of the parse tree. Each output line shows one tree node. Child nodes are indented with respect to their parent node. The columns are:
    1. An asterisk if the node starts a new text line, or a hyphen if the node follows the previous node without intervening whitespace.
    2. The node type.
    3. For text nodes, the text contents. For other nodes, the attributes, if any.

okay this one is lowkey my fave, it's giving x-ray vision into the parser 🔥

• lint — Do not produce any output, only error messages. Can be combined with -W. she just judges, silently, and tells you what's wrong 💀

• -W — Report warnings on standard error output, and if any occur, raise the “EXIT STATUS” to at least 2. so she's watching 👀

A subset of DocBook 5.1 elements are recognized, as well as some elements from earlier versions. The parser is optimized for robustness even on invalid input, always producing some output on a best-effort basis. Input is not required to be well-formed, nor to adhere to DocBook syntactic or semantic requirements. literally she does not gatekeep, she will work with whatever mess you hand her 😭💖

Unknown elements are ignored in the sense that they do not affect formatting and only their content is rendered. Unknown attributes are silently discarded. no drama, no notes, just vibes ✨

In addition to DocBook elements, the following constructs are handled:

• <! DOCTYPE ... [ <!ENTITY name "definition" > ]> Internal subset declaration to define an XML entity.
• <! DOCTYPE ... [ <!ENTITY name SYSTEM "file" > ]> Internal subset declaration to define an XML entity using an external file.
• <! DOCTYPE ... [ <!ENTITY % name SYSTEM "file" > %name ]> Internal subset declaration to include an external file that is supposed to contain entity declarations.
• < mml:... > Elements from the MathML namespace. These are translated to eqn(7).
• < xi:include ... href="file"> Include an external DocBook file into the current document.

---

🎀 EXIT STATUS 🎀

The docbook2mdoc utility exits with one of the following values, and yes each one has a personality:

• 0 — No error occurred, and if -W was specified, no warning occurred either. the slay ending 🎉
• 2 — At least one warning occurred, but no error, and -W was specified. she's fine, she's just being loud about it 🙈
• 3 — At least one parsing error occurred. oop 💀
• 5 — Invalid command line arguments were specified. No input files have been read. she didn't even look at your files, bestie.
• 6 — Memory was exhausted. Parsing was aborted immediately. RIP, she ran out of brain cells 😭

---

🧚 EXAMPLES 🧚

To pipe a DocBook document foo.xml through mandoc(1) and a pager:

$ docbook2mdoc foo.xml | mandoc -l

periodt. that's the whole trick, go off 🔥

---

👑 DIAGNOSTICS 👑

Messages displayed by docbook2mdoc follow this format:

docbook2mdoc: file:line:column: level: message

The first three fields identify the file name, line number, and column number of the input file where the message was triggered. The line and column numbers start at 1. so precise, so cunty, we love a girl who knows exactly where the problem is 💅

Message levels have the following meanings:

• fatal — An operating system error occurred, typically memory exhaustion, and parsing was aborted immediately. like, the whole thing is over, no coming back from this one 💀
• error — Indicates a risk of information loss or severe misformatting, for example caused by unknown elements or missing include files. not great, not terrible, but seriously not great 😬
• warning — Indicates a risk that the information shown or its formatting may mismatch the author's intent in minor ways. For example, mismatched or missing end tags are classified as warnings. lil oopsie, minor, but she WILL tell you 🫶

---

🌈 SEE ALSO 🌈

mandoc(1), eqn(7), mdoc(7)

go read those too bestie, they're the supporting cast and they ate 💖

---

⭐ AUTHORS ⭐

docbook2mdoc was written by Kristaps Dzonsons <kristaps@bsd.lv> and Ingo Schwarze <schwarze@openbsd.org>. legends, honestly, the blueprint 👑

---

ok that's the whole page, and yes, you read it all, I'm so proud of you 🥹💜

---

and that's a wrap! this Debian build of the page is dated May 2, 2019, so if you're reading it in the future, hi, hope you're slaying 🦋✨ mwah, bye bestie 💖