The manual pages trigger many formatter warnings

[alejandro-colomar]

I've run the Linux man-pages build system, which can lint many issues in manual pages, on neomutt's manual pages.

$ make -C ~/src/linux/man-pages/man-pages/master/ -k lint-man MANDIR=~/src/mutt/neomutt/main/
make: Entering directory '/home/alx/src/linux/man-pages/man-pages/master'
MKDIR	.tmp/man/docs/
LINT (mandoc)	.tmp/man/docs/pgpewrap.1.lint-man.mandoc.touch
mandoc: /home/alx/src/mutt/neomutt/main//docs/pgpewrap.1:20:16: WARNING: cannot parse date, using it verbatim: TH May 2013
mandoc: /home/alx/src/mutt/neomutt/main//docs/pgpewrap.1:25:2: WARNING: skipping paragraph macro: PP after SH
mandoc: /home/alx/src/mutt/neomutt/main//docs/pgpewrap.1:29:2: WARNING: skipping paragraph macro: PP after SH
make: *** [share/mk/lint/man/man.mk:32: .tmp/man/docs/pgpewrap.1.lint-man.mandoc.touch] Error 1
LINT (mandoc)	.tmp/man/docs/smime_keys.1.lint-man.mandoc.touch
mandoc: /home/alx/src/mutt/neomutt/main//docs/smime_keys.1:25:88: STYLE: input text line longer than 80 bytes: smime_keys \- Utilit...
mandoc: /home/alx/src/mutt/neomutt/main//docs/smime_keys.1:31:86: STYLE: input text line longer than 80 bytes: The purpose of this ...
mandoc: /home/alx/src/mutt/neomutt/main//docs/smime_keys.1:32:92: STYLE: input text line longer than 80 bytes: used by neomutt to s...
mandoc: /home/alx/src/mutt/neomutt/main//docs/smime_keys.1:23:18: WARNING: cannot parse date, using it verbatim: TH May 2009
mandoc: /home/alx/src/mutt/neomutt/main//docs/smime_keys.1:27:2: WARNING: skipping paragraph macro: PP after SH
mandoc: /home/alx/src/mutt/neomutt/main//docs/smime_keys.1:35:2: WARNING: skipping paragraph macro: PP empty
make: *** [share/mk/lint/man/man.mk:32: .tmp/man/docs/smime_keys.1.lint-man.mandoc.touch] Error 1
LINT (mandoc)	.tmp/man/docs/mbox.5.lint-man.mandoc.touch
mandoc: /home/alx/src/mutt/neomutt/main//docs/mbox.5:9:12: WARNING: cannot parse date, using it verbatim: TH February 19th, 2002
mandoc: /home/alx/src/mutt/neomutt/main//docs/mbox.5:147:2: WARNING: skipping paragraph macro: PP empty
make: *** [share/mk/lint/man/man.mk:32: .tmp/man/docs/mbox.5.lint-man.mandoc.touch] Error 1
LINT (mandoc)	.tmp/man/docs/mmdf.5.lint-man.mandoc.touch
mandoc: /home/alx/src/mutt/neomutt/main//docs/mmdf.5:8:12: WARNING: cannot parse date, using it verbatim: TH February 18th, 2002
mandoc: /home/alx/src/mutt/neomutt/main//docs/mmdf.5:40:2: WARNING: skipping paragraph macro: br before sp
mandoc: /home/alx/src/mutt/neomutt/main//docs/mmdf.5:42:2: WARNING: skipping paragraph macro: br after sp
mandoc: /home/alx/src/mutt/neomutt/main//docs/mmdf.5:45:2: WARNING: skipping paragraph macro: br after br
mandoc: /home/alx/src/mutt/neomutt/main//docs/mmdf.5:55:2: WARNING: skipping paragraph macro: br before sp
mandoc: /home/alx/src/mutt/neomutt/main//docs/mmdf.5:57:2: WARNING: skipping paragraph macro: br after sp
make: *** [share/mk/lint/man/man.mk:32: .tmp/man/docs/mmdf.5.lint-man.mandoc.touch] Error 1
LINT (tbl comment)	.tmp/man/docs/pgpewrap.1.lint-man.tbl.touch
LINT (tbl comment)	.tmp/man/docs/smime_keys.1.lint-man.tbl.touch
LINT (tbl comment)	.tmp/man/docs/mbox.5.lint-man.tbl.touch
/home/alx/src/mutt/neomutt/main//docs/mbox.5:1: spurious '\" t' comment:
'\" t
make: *** [share/mk/lint/man/man.mk:42: .tmp/man/docs/mbox.5.lint-man.tbl.touch] Error 1
LINT (tbl comment)	.tmp/man/docs/mmdf.5.lint-man.tbl.touch
make: Target 'lint-man' not remade because of errors.
make: Leaving directory '/home/alx/src/linux/man-pages/man-pages/master'

I'll prepare some fixes.

There are also things that aren't reported by those lints, but which produce wrong formatting in manual pages, such as using a single space after a period. That isn't warned about, because it's not exactly easy to detect by a program, but there's intention to warn about them too if we find out how to do it without false positives. Anyway, I'll fix those too.

[flatcap]

Sorry, the man pages have always been neglected.
We've added extra bits over the years, but without any understanding.

I'm afraid it gets worse still when it comes to the auto-generated sections.
docs/makedoc.c tries to generate nroff from docs/config.c.
The docs contain some 3-column tables which get completely mangled.

I got as far as figuring out the nroff syntax, but no further:

.TS
box;
lb|lb|lb
l|l|l .
Expando	Flag	Description
_
%a	A	account url
%p	B	port
%P	.	port if specified
%s		news server name
%S	A	url schema
%u	B	username
.TE

I'll prepare some fixes.

Thank you ❤️