CVSROOT: /cvs
Module name: src
Changes by: [email protected] 2025/07/09 06:49:32
Modified files:
usr.bin/mandoc : man_validate.c
Log message:
If the first argument of the .TH macro (the manual page name) is an
empty string (as in: .TH "" ...), which is invalid syntax, use the
fixed string "UNTITLED" instead, in the same was as in mdoc(7).
This is needed because if *both* the first and the second arguments are
empty strings (as in: .TH "" "" ...), makewhatis(8) assumes the file is
not a valid man(7) file at all and marks it as preformatted (FORM_CAT)
in mandoc.db(5) such that man(1) displays it verbatim, without
formatting it.
One subtle difference to mdoc(7) remains: if there is no .Dt macro
at all, -mdoc also sets the title to "UNTITLED", which is OK because
the mdoc(7) parser is only used if the user explicitly requested -mdoc
or choose_parser() in read.c detected mdoc(7) by finding a .Dd macro.
The man(7) parser, on the other hand, is always used as a fallback,
even if neither the user requested it with -man, nor choose_parser()
detected a .TH macro. Thus, for man(7), the "" -> "UNTITLED"
replacement is only done when the validation module finds a .TH ""
macro, but not when there is no .TH macro at all, in order to not
break verbatim display of preformatted manual pages.
Problem reported by Robert Kirkman <rkirkman at termux dot dev>,
see https://github.com/termux/termux-packages/pull/25294 .
An example of a file triggering the problem is the totally crappy file
https://android.googlesource.com/platform/packages/modules/adb/+show/refs/heads/main/docs/user/adb.1.md
(which is hardly worth calling a "manual page"). When the equally crappy
pandoc(1) program is used to convert that to man(7) format - even though
calling the result a "man(7) file" is quite a stretch - that file
contains this invalid line triggering the issue: .TH "" "" "" ""
