Hi,
this mail is a heads-up regarding some changes to the syntax
validation of base system manual pages. It is relevant to people
who sometimes edit manuals or often run builds.
Yesterday, i fixed the last handful of cases where mandoc(1) used
to throw FATAL errors. That is, since today, if mandoc(1) can open
a file, it will now always produce some output - at worst, that may
be almost empty, but it will never fail outright (except when there
is a bug in mandoc, as opposed to a bug in the manual).
In other words, "mandoc -Tlint -Wfatal" can no longer fail on
readable files, and consequently, since today, this command is no
longer run during "make build". In principle, this shortens the
build log and speeds up the build - on a modern machine, it's
probably not very noticeable, but it might save a bit of time on
older architectures.
Theo suggested adding a new target to validate the syntax of
base system manual pages, and that was easy to do. You are welcome
to use it in two situations:
1. You are editing manual pages.
In the small subtree you are working on, run
make manlint
That runs "mandoc -Tlint" on all manuals in that subtree and
errors out if there is a warning or an error. If you consider
the complaint reasonable, fix it and rerun. If you suspect a
false positive, feel free to talk to me, i might be able to
improve "mandoc -Tlint".
2. You wonder whether manuals are good in general.
Feel free to run something like
make -k manlint 2>&1 | grep ^mandoc:
over the whole tree (that takes about 16 seconds on my notebook,
checking 2248 files) or over large subtrees. If you spot
something that you consider a real issue, and unless it's in
files maintained by some upstream, sending patches might make
sense. Before sinking a lot of time into such work, feel free
to ask me whether the work you plan to do makes sense.
Here is a snapshot of the current status:
bin: 5 warnings
games: clean
gnu: 737 warnings, 2000 errors
lib: 318 warnings, 2 errors
libexec: clean
sbin: 7 warnings
share: 42 warnings
sys: 2 warnings
usr.bin: 28 warnings
usr.sbin: 449 warnings (207 nsd, 179 unbound, 63 elsewhere)
Yours,
Ingo
P.S.
One thing i'm planning to do in the future is to split the mandoc
ERROR level into two. After the split, ERROR will be for syntax
errors in the respective manual page, i.e. for things that must
be fixed by removing markup bugs from the manual page. Typically,
if there is an ERROR, it won't work well with groff(1), either.
A new level (maybe UNSUPP or UNIMPL) will be used for low-level
roff(7) constructions that work with groff(1), but are not supported
by mandoc(1). This distinction is intended to make life easier for
porters. When it's done, checking a port gets simpler: If there
is UNSUPP, USE_GROFF - if there are only WARNINGs and ERRORs, no
need to. But that's not available yet. Right now, you still need
to watch out for ERRORs and then figure out manually of which kind
they are, and whether or not they require USE_GROFF.
