Rewrite half of this, i was completely unaware how bad it was.
Remove several lies, lots of duplicate information,
and a lengthy discussion of features we don't support.
Clarify the wording in some places and make it more concise in others.
Delete examples from where they don't belong
and write a new EXAMPLES section from scratch.

test inter-column spacing

Implement spacing of columns as defined in the table layout;
this is for example used by lftp(1)
and, ironically, misused by our very own tbl(7) manual...

warn about .Ns macros that have no effect because they are followed
by an isolated closing delimiter; inspired by mdoclint

catch up with the recent eqn(7) improvements

Complete rewrite of the lexer in a single function with four operation
modes instead of four functions, resulting in considerable
simplification, fifty lines less of code, fifteen fewer automatic
variables, and several bug fixes, for example:

1. The delim control statement consumes exactly two bytes of input,
requires no whitespace after these two bytes, and does not treat
quotes in any special way.
2. If the argument of left, right, gfont, gsize, or size is defined
as an alias, only the first word of the value is used as the
delimiter, font name, or font size.
3. If a back, fwd, down, or up keyword is followed by another keyword
instead of the required number, GNU eqn does nothing useful, but
typically errors out.  So no need to have special handling (with
an ugly goto!) for it in mandoc.

Also getting rid of one pointless static buffer and twelve redundant
calls to strlcpy(3).

when splitting a composite word,
do not forget to close the inserted list box

Catch typos in .Sh names; suggested by jmc@.

I'm using a very simple, linear time / zero space fuzzy string
matching heuristic rather than a full Levenshtein metric, to keep
the code both simple and fast.

test new MT macro

cope with changes in BASE messages

add support for the MT and ME mailto macros, used for example in wg(8);
patch from bentley@

delete useless .Ns macro that jmc@ found with mdoclint(1)

document message "unknown architecture"

operating system dependent message about unknown architecture;
inspired by mdoclint

delete old, undocumented, obsolete section names that nobody uses

in the base system, suggest leaving .Os blank; inspired by mdoclint

Split -Wstyle into -Wstyle and the even lower -Wbase, and add
-Wopenbsd and -Wnetbsd to check conventions for the base system of
a specific operating system.  Mark operating system specific messages
with "(OpenBSD)" at the end.

Please use just "-Tlint" to check base system manuals (defaulting
to -Wall, which is now -Wbase), but prefer "-Tlint -Wstyle" for the
manuals of portable software projects you maintain that are not
part of OpenBSD base, to avoid bogus recommendations about base
system conventions that do not apply.

Issue originally reported by semarie@, solution using
an idea from tedu@, discussed with jmc@ and jca@.

Delete .St -p1003.1-2013.
It is an OpenBSD addition that did not get used a single time in
three years, and groff did not pick it up either, so removing it
does not affect any existing manuals anywhere.
Cleanup suggested by jmc@, OK bentley@.

Consistently treat character escape sequences as operators,
not as letters, even if their names contain letters.

This is certainly not perfect, but code to recognize that \(*a is
not an operator but a letter would need a huge table, or Unicode
character property support, which won't happen at this time.

eqn(1) output operator translation

splitting a text box sometimes requires wrapping it in a list

Stop using "mdocml" as an official name.
Prefer mandoc.bsd.lv to mdocml.bsd.lv.

Write text boxes as <mi>, <mn>, or <mo> as appropriate,
and write fontstyle or fontweight attributes where required.
Missing features reported by bentley@.

Simplify font handling:
1. Inherit the font attribute from the parent box, such that iteration
is no longer required to find the current font.
2. For well-known function name tokens, do not insert an EQN_LISTONE
box into the AST; simply set the font attribute of the text box
itself that contains the name.

Also improve word splitting of unquoted strings in default font mode:
3. Split between numbers and punctuation because both will soon get
different HTML markup.
4. Do not split between letters.  With the newly ubiquitious font
attributes, all formatters will be able to figure out what to do
without putting each letter into a separate box.

Fix font selection for text boxes in the terminal formatter.
Issue reported by bentley@.

The AST data structure is powerful enough that all required
information can easily be provided in the parser, and no change
of the formatting code is needed.

Outside explicit font context, give every letter its own box.
The formatters need this to correctly select fonts.
Missing feature reported by bentley@.

quoted words are not parsed for defined keys

Recognize well-known functions names (the same that Heirloom recognizes,
which includes those recognized by groff) and wrap them in a roman box
unless they already are in roman context.
Missing feature reported by bentley@.

KNF: remove parentheses from switch case labels; no binary change

Fix a regression in the previous revision:
When there is no link description, reuse the URI.
Reported by tj@ and bentley@.

Implement appending to standard man(7) and mdoc(7) macros with .am.

With roff_getstrn(), provide finer control which definitions
can be used for what:
* All definitions can be used for .if d tests and .am appending.
* User-defined for \* expansion, .dei expansion, and macro calling.
* Predefined for \* expansion.
* Standard macros, original or renamed, for macro calling.

Several related improvements while here:
* Do not return string table entries that have explicitly been removed.
* Do not create a rentab entry when trying to rename a non-existent macro.
* Clear an existing rentab entry when the external interface
roff_setstr() is called with its name.
* Avoid trailing blanks in macro lines generated from renamed
and from aliased macros.
* Delete the duplicate __m*_reserved[] tables, just use roff_name[].

style message about duplicate RCS ids; inspired by mdoclint

style message about missing RCS ids; inspired by mdoclint

if .in is used inside the .TP head, it's always relative

tables leak tab settings to subsequent text

correct handling of blank lines after \c

properly set the default indentation
such that even pages without any .SH macros get it

Multiple tbl(7) improvements:
* Do not discard data that lacks a matching layout cell but remains
within the number of columns of the table as a whole.
* Do not insert dummy data rows for any layout row starting with a
horizontal line, but only for layout rows that would discard all
the data on a matching non-empty data row.
* Print horizontal lines specified in the layout even if there is
no matching data cell.
* Improve the logic for extending vertical lines to adjacent rows,
for choosing cross marks versus line segments, and some related details.

round default width of tbl(7) text blocks in the same way as groff

implement so-called absolute horizontal motion: \h'|...',
used for example by zoem(1)

Naive implementation of the roff(7) .po (page offset) request.

This clearly works when .po is called on the top level, but might
not be sophisticated enough if people call .po inside indentation-changing
contexts, but i haven't seen that in manual pages (yet :).

add the \(ru (0.5m baseline ruler) character escape sequence,
abused by mail/nmh; groff_char(7) confirms that this really exists

simple implementation of the roff(7) .als (macro alias) request,
sufficient for pages using po4a(1)

let \l use the right fill character

improve rounding rules for scaling units
in horizontal orientation in the terminal formatter

harmless, but weird typo; found with afterstep_faq(1)

implement the roff(7) d (macro or string defined) conditional

implement roff(7) .rj (right justify) request

implement the roff(7) \p (break output line) escape sequence

Partial support for the \n[an-margin] number register.

Manuals autogenerated from reStructuredText are reckless enough
to peek at this non-portable, implementation-dependent, highly
groff-specific internal register - for no good reason, because the
man(7) language natively provides in a much simpler way what they
are trying to emulate here with much fragility.

A full implementation would be very hard because it would require
access to output-device-specific formatting data at the roff(7)
preprocessor stage, which mandoc doesn't support at all.
So hardcode a few magic numbers as reStructuredText expects them
for terminal output.  For other output modes (like HTML), code using
this register is utterly broken anyway.

If the layout is empty except for requesting a left vertical frame,
record that detail in struct tbl_opts, such that term_tbl() can do
correct column calculations and doesn't prematurely break lines.
Fixes the tbl/layout/empty regression test that got broken when
line breaking in text block cells was implemented.

Delete the arbitrary range restriction for -Owidth.
We provide users with tools.  We don't attempt to prevent them from
using them in stupid ways: depending on the context, not every
stupid-looking use is necessarily actually stupid, and not every
stupidity can be automatically detected anyway, so don't even try.

fix the interaction of the allbox option with spanned cells in the layout

Explicitly ignore .br, .ce, and .sp inside tbl(7) text blocks.
With the current code structure, they would appear at the wrong
place in the syntax tree, so it is better to not insert them
into the tree at all and issue an UNSUPP message instead.

test the new allbox and wrapping features

Two minor fixes for the "allbox" modifier:
1. It does not reduce explicit "||" in the layout to "|".
2. It does not cause three horizontal lines at the end of a table,
even if the table ends with an explicit "_" data line.

If a tbl(7) layout contains a 'w' (minimum width) modifier for a
given column, that column contains no literal or numeric cell of
larger width, and all text block cells in that column can be line
wrapped to fit into that minimum width, groff does not increase
that column width beyond the specified minimum: so do the same.

implement the tbl(7) "allbox" option;
used for example by curs_getch(3) and GLwDrawingArea(3)

fix column width calculation for text block cells

Implement automatic line breaking
inside individual table cells that contain text blocks.
This cures overlong lines in various Xenocara manuals.

ooops, fix a glitch in the previous commit...

Style message about legacy man(7) date format in mdoc(7) documents
and operating system dependent messages about missing or unexpected
Mdocdate; inspired by mdoclint(1).

Style message about legacy man(7) date format in mdoc(7) documents
and operating system dependent messages about missing or unexpected
Mdocdate; inspired by mdoclint(1).

style message about missing .Fn markup; inspired by mdoclint

Do not issue the message "no blank before trailing delimiter" for .No.
In practice, that message only matters inside .Bf, and even there, it
can occasionally be a false positive.  In all other cases, it usually
is a false positive, so it is better to drop it outright.
Suggested by jmc@.

add forgotten file

fix order of messages

Reduce false positives for the "no blank before trailing delimiter" message.
This brings us down to one false positive for about every 18 pages.

minor markup simplifications

style message about missing blank before trailing delimiter;
inspired by mdoclint(1), and jmc@ considers it useful

do not break the line between Bsx/Bx/Fx/Nx/Ox/Dx and its arguments

Properly reinitialize roffce_node between parses,
or this may crash with use-after-free in makewhatis(8);
reported by jmc@, thanks!

Implement w layout specifier (minimum column width).
Improve width calculation of text blocks.
Reduces the groff/mandoc diff in Base+Xenocara by about 800 lines.

make the internal a2roffsu() interface more powerful by returning
a pointer to the end of the parsed data, making it easier to
parse subsequent bytes

warning about unknown .Lb arguments; inspired by mdoclint(1)

style checks related to .Er; inspired by mdoclint(1)

Also catch "new sentence, new line" if there are three blanks
between the sentences.  Thomas Klausner says he has seen some
of these, and i don't see any false positives.

Make "new sentence, new line" detection stricter:
Also catch cases where the new sentence starts with a one-letter word
and the input line is broken right after that word.
Suggested by Thomas Klausner <wiz @ NetBSD>.

It's merely a three-bit diff, changing one byte from 0x34 to 0x33,
so what can possibly go wrong...

Prepare the terminal driver for filling multiple columns in parallel,
second step: make the per-column byte pointer persistent across
term_flushln() calls, such that a subsequent call can continue at
the point where the previous call left.  If more than one column
is in use, return from term_flushln() when the column is full,
rather than breaking the output line.

No functional change, because nothing sets up multiple columns yet.

Prepare the terminal driver for filling multiple columns in parallel,
first step: split column data out of the terminal state struct into
a new column state struct and use an array of such column state
structs.  No functional change.

The \h escape sequence provides another method for moving backwards,
and after that, previously written output gets overwritten, but
overwriting with blanks does *not* erase previously written content.
Yes, manual pages exist that are crazy enough to rely on that...

Implement the roff(7) .rn (rename macro or string) request.
Renaming a user-defined macro is very simple: just copy
the definition to the new name and delete the old name.
Renaming high-level macros is a bit tricky: use a dedicated
key-value-table, with non-standard names as keys and standard
names as values.  When a macro is found that is not user-defined,
look it up in the "renamed" table and translate it back to the
standard name before passing it on to the high-level parsers.

document the new .ce implementation

Minimal implementation of the roff(7) .ce request (center a number
of input lines without filling).
Contrary to groff, high-level macros abort .ce mode for now.

Implement the roff(7) .mc (right margin character) request.
The Tcl/Tk manual pages use this extensively.
Delete the TERM_MAXMARGIN hack, it breaks .mc inside .nf;
instead, implement a proper TERMP_BRNEVER flag.

Make term_flushln() simpler and more robust:
Eliminate the "overstep" state variable.
The information is already contained in "viscol".
Minus 60 lines of code, no functional change intended.

Pure preprocessor implementation of the roff(7) .ec and .eo requests
(escape character control), touching nothing after the preprocessing
stage and keeping even the state variable local to the preprocessor.
Since the escape character is also used for line continuation, this
requires pulling the implementation of line continuation from the
input reader to the preprocessor, which also considerably shortens
the code required for that.

When the escape character is changed, simply let the preprocessor
replace bare by escaped backslashes and instances of the non-standard
escape character with bare backslashes - that's all we need.

Oh, and if anybody dares to use these requests in OpenBSD manuals,
sending a medium-sized pack of axe-murderers after them might be a
worthwhile part of the punishment, but probably insuffient on its own.

ignore blank lines in man(7) next line scope;
strange groff edge case behaviour found in multimedia/mjpegtools

enable -Wstyle by default in -Tlint; OK jmc@

Partial implementation of \h (horizontal line drawing function).
A full implementation would require access to output device properties
and state variables (both only available after the main parser has
finalized the parse tree) before numerical expansions in the roff
preprocessor (i.e., before the main parser is even started).

Not trying to pull that stunt right now because the static-width
implementation committed here is sufficient for tcl-style manual pages
and already more complicated than i would have suspected.

add about 15 missing character escape sequences found in groff_char(7);
triggered by multimedia/mkvtoolnix mkvmerge(1) using \(S2

Minimal implementation of the \h (horizontal motion) escape sequence.
Good enough to cope with the average DocBook insanity.

STYLE message about full stop at the end of .Nd; inspired by mdoclint(1)

STYLE message about missing use of Ox/Nx/Fx/Dx; OK jmc@ wiz@

tweak previous; from jmc@

STYLE message about useless macros we don't want (Bt Tn Ud);
not a WARNING because they don't endanger portability

fix formatting of intermediate punctuation in .Lk

Macro argument quoting does not prevent recognition of punctuation
and of called macros.

This bug affects almost all macros, and fixing it simplifies the
code.  It is amazing that the bogus ARGS_QWORD feature got implemented
in the first place, and then carrier along for more than eight years
without anybody ever noticing that it was pointless.

Reported by Leah Neukirchen <leah at vuxu dot org>, found on Void Linux.

Use [ rather than [[ for portability,
in particular since it makes no difference in the case at hand.
Reported by Leah Neukirchen <leah at vuxu dot org> (Void Linux).

Delete the -T xhtml command line option.
It has been obsolete for more than two years.
Use -T html.