GitLab

Seems like docbook2man isn't perfect when it comes to XML. Can't blame it for that, since XML is a mess anyway, but it goes.

Subsections in the CONFIGURATION FILE FORMAT section are wrong. They get uppercased (although subsections are usually lowercase), and converted to groff without proper quoting.

Steps to reproduce

1. Open man 5 fonts-conf
2. Scroll down.

Expected output

   <include ignore_missing="no" prefix="default">

Actual output

Rendered man page:

   <INCLUDE IGNORE_MISSING= NO" PREFIX="DEFAULT">"

Groff source:

.SS "<INCLUDE IGNORE_MISSING=\&"NO\&" PREFIX=\&"DEFAULT\&">"

Solution

The proper way to generate groff source for that is to char-escape double quotes. According to groff_char(7), ASCII double quote can be unambiguously represented as \[dq].

.SS <include ignore_missing=\&\[dq]no\&\[dq] prefix=\&\[dq]default\&\[dq]>

Also, would be better to highlight attribute values with underline style, which in man pages often stands for user input placeholder. That would require breaking up ` in source *.sgml sources and possibly inventing new elements.