typo; diff from fcambus@

\s with arbitrary arg delimiters

In HTML output, correctly render .Bd -unfilled in proportionally-spaced
font, rather than with the monospace font appropriate for .Bd -literal.
This fixes a minibug reported by anton@.

Implemented by no longer relying on the typical browser default of
"pre { font-family: monospace }" but instead letting <pre> elements
inherit the font family from their parent, then adding an explicit CSS .Li
class only for those displays where the manual page author requested it
by using the -literal option on the .Bd macro.

Append .html suffix to temporary files enabling browsers to recognise it.

Occasionally one might read a manual page in a webbrowser, e.g.
"MANPAGER=firefox man -T html jq", however temporary files created for
pagers lack file extensions and most web browsers are unable to detect a
file's content without it.

Special case mandoc(1)'s HTML output format by appending the ".html" suffix
to file names such that browsers will actually render HTML as such instead
of showing it as plain text.

Idea and patch from kn@, with minor help from me.

double .TH in man(7)

more about .Bd -unfilled

Rename syntax test of the \O escape sequence (suppress output groff
extension; mandoc only implements syntax checking but ignores the
sequence) to please Bill Gates and didickman@: avoid path names that
only differ by case, like o.in vs. O.in.

MANWIDTH

old groff_char(7) reported by kamil at NetBSD

Delete a sentence pointing to "the Predefined Strings subsection
of the roff(7) manual."  Such a subsection does not exist, and i
do not see why it should.  Predefined strings are an obsolete
feature of macro packages, not a feature of the roff language.

Finally get rid of the "overflow: auto" property of ".Bl-tag > dd"
which has long been know to cause ugly and pointless scroll bars.

Matthew Martin <phy1729 at gmail dot com>
helpfully explained the following two points to me:
1. What we need to do here is establish a new block formatting
context such that the first line of the <dd> content moves down
rather than to the right if the preceding <dt> is wide.
2. A comprehensive list of methods
to establish block formatting context is available in:
https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Block_formatting_context

In that list, i found that "column-count: 1" does the job.
It is part of CSS Multi-column Layout Level 1.
While that is still in Working Draft status according to
https://www.w3.org/Style/CSS/current-work ,
it is fully supported by all browsers according to
https://developer.mozilla.org/en-US/docs/Web/CSS/column-count ,
probably because it was already part of the second draft of this
standard almost 20 years ago: WD-css3-multicol-20010118.

Promote section headers that can can be used unmodified as fragment
identifiers from TAG_WEAK to TAG_STRONG,
such that for example ...#DESCRIPTION always works.
Suggested by Aman Verma on the discuss@ list.

Correct an embarrassing spelling mistake:
The last name of the author of groff is "Clark".

Improve the HISTORY and AUTHORS sections, using information
received from Douglas McIlroy in private mail:
https://manpages.bsd.lv/history/mcilroy_26_10_2020.txt

error message simplifications requested by deraadt@

The GNU tbl(1) program contained in the groff package internally
uses roff(7) tabulator settings to implement tables, and it used
to leak the changed tabulator settings from tables to the subsequent
roff(7) code.  In mandoc/tbl_term.c rev. 1.54 (June 17, 2017), code
was added to be bug-compatible with groff.

In commit d0e03cf6 (Oct 20, 2020), GNU tbl(1) changed behaviour
to save the tabulator settings before starting a table and restore
them afterwards.  Adjust mandoc for compatibility.

Since mandoc implements tables without using roff(7) tabulator
settings, saving and restoring tabulator settings is not needed in
mandoc.  Simply deleting the code that changed tabulator settings
by reverting tbl_term.c rev. 1.54 is sufficient in mandoc.
Also adjust the desired output of the regression tests
to match the new behaviour of both groff and mandoc.

Treat \*[.T] in the same way as \*(.T rather than calling abort(3).
Bug found because the groff-current manual pages started using the
variant form of this predefined string.

In HTML output, avoid printing a newline right after <pre>
and right before </pre> because that resulted in vertical
whitespace not requested by the manual page author.

Formatting bug reported by
Aman Verma <amanraoverma plus vim at gmail dot com> on discuss@.

add missing mention of Werner Lemberg,
noticed by Werner himself on <groff at gnu dot org>;
while here, add missing .An macros

add example to apropos.1 to list all manuals in a given section;
patch from ians@

Element next-line scopes can nest.  Consequently, even when closing
one element next-line scope, the MAN_ELINE flag must not yet be
cleared if the parent macro is another element macro having next-line
scope, or an assertion failure is caused if all this is wrapped in
another macro that has block next-line scope, for example .TP.
Bug found in an afl run performed by Jan Schreiber <jes at posteo dot de>.

Do not abuse assert(3) to react to absurd input; the purpose of assert(3)
only is to catch internal inconsistencies in the program itself.
Issue found in an afl run performed by Jan Schreiber <jes at posteo dot de>.

Instead, just cut down unreasonably wide spacing requested by the document
to a narrower width.

assertion found in jes@'es afl run: .TS .if n .ce

After .ti, there are many reasons why the offset may change, so setting
it back later requires a guard against underflow, or subsequent assertions
may fail.
Issue found in an afl run performed by Jan Schreiber <jes at posteo dot de>.

Fix two issues with .po (page offset) formatting:
1. Truncate excessive offsets to a width reasonable in the context
of manual pages instead of printing excessively long lines
and sometimes causing assertion failures;
found in an afl run performed by Jan Schreiber <jes at posteo dot de>.
2. Remember both the requested and the applied page offset; otherwise,
subtracting an excessive width, then adding it again, would end up
with an incorrectly large offset.
While here, simplify the code by reverting the previous offset up front,
and also add some comments to make the general ideas easier to understand.

If .ti had an excessive argument, using it was attempted, in some
cases resulting in an assertion failure.  Instead, truncate the
temporary indent to a width reasonable in a manual page.

I found the issue in an afl run
that was performed by Jan Schreiber <jes at posteo dot de>.

Do not indent by SIZE_MAX/2 when .ce occurs inside explicit no-fill mode.
While here, drop two unused arguments from the function term_field();
the related work was already done by term_fill() before this commit.

I found the bug in an afl run
that was performed by Jan Schreiber <jes at posteo dot de>.

Ignore unreasonably large spacing modifiers in tbl layouts.

Jan Schreiber <jes at posteo dot de> ran afl on mandoc and it turned
out mandoc tried to use spacing modifiers so large that they would
trigger assertion failures in term_ascii.c, function locale_advance().

more info from John Gardner about ASCII control chars in roff(7) input

Remove a lie reported by Jamie Landeg-Jones <jamie at catflap dot org>:
The times when -T man may have expanded .so requests are long gone,
nor would such a feature be useful.  Use soelim(1) if you need that.

Fix a regression caused by the insertion of two new tokens,
which unintentionally made the -O tag= argument mandatory,
breaking commands like "man -akO tag Ic=ulimit".
Noticed while answering questions from Ian Ropers.

Make it more explicit that the statement "-O tag does not work with less(1)"
only applies to -T html output mode, and why.  Of course, -O tag works
just fine with less(1) in the -T ascii and -T utf8 output modes.
Potential for confusion pointed out by Ian Ropers.

Avoid artifacts in the most common case of closing conditional blocks
when no arguments follow the closing brace, \}.
For example, the line "'br\}" contained in the pod2man(1) preamble
would throw a bogus "escaped character not allowed in a name" error.
This issue was originally reported by Chris Bennett on ports@,
and afresh1@ noticed it came from the pod2man(1) preamble.

add a forgotten "#if HAVE_PLEDGE";
patch sent in by <alexander dot gromnitsky at gmail dot com>
who found the problem the hard way on Fedora 32

Put the code handling \} into a new function roff_cond_checkend()
and call that function not only from both places where copies
existed - when processing text lines and when processing request/macro
lines in conditional block scope - but also when closing a macro
definition request, such that this construction works:

.if n \{.de macroname
macro content
.. \} ignored arguments
.macroname

This fixes a bug reported by John Gardner <gardnerjohng at gmail dot com>.

While here, avoid a confusing decrement of the line scope counter
in roffnode_cleanscope() for conditional blocks that do not have
line scope in the first place (no functional change for this part).
Also improve validation of an internal invariant in roff_cblock()
and polish some comments.

trivial sync with OpenBSD
in parts of these files that are not used by -portable;
consequently, no functional change

trivial adjustment of the desired test results
after getting rid of the "copyless" crutch

adjust test framework to not require a tty

undocumented options -O outfilename and -O tagfilename
to support regression testing without a tty;
no user visible change intended

Switch the default pager from "more -s" to "less".

POSIX explicitly allows using a different default pager if that is
documented.  Nowadays, the pager provided in most operating systems
is less(1).  Our man(1) implementation uses less(1) features that
traditional more(1) did not provide, in particular tagging.  Besides,
as noted by deraadt@, the user interface of less(1) is slightly
more refined and preferable over the user inferface of more(1).
This switch was originally suggested by Ian Ropers.

In ./configure, test whether less(1) is available.  If not, fall
back to more(1).  In ./configure.local, support overriding the
automatic test by setting BINM_PAGER.

As explained by jmc@ and deraadt@, the -s flag was added a very
long time ago when an antique version of groff(1) had an annoying
bug in terminal output that would randomly display blank lines in
the middle of pages.  Clearly, -s has no longer been needed for
many years, so drop it from the default pager invocation.

OK deraadt@ jmc@ martijn@ job@ on the OpenBSD version of this patch.

Support the "powerpc64" architecture name.
The first file using it in .Dt was just committed by kettenis@.

Briefly mention groff_mdoc(7) below SEE ALSO.  While both authoritative
manual pages document the same content, comparing can occasionally help
in cases of doubt, and some people may prefer one style, some the other.
While here, modernize a few .Lks from http:// to https://.
OK jmc@

more details about ASCII control characters

Provide a real feature test for __attribute__().
Looking at version numbers like __GNUC__ is always a bad idea.
Believe it or not, this even makes ./configure shorter by one line.

Because mandoc_aux.h and mandoc.h use __attribute__, all files that
include mandoc_aux.h or mandoc.h need to include config.h, too.
It is suspected that for example IRIX needs this, or it is likely
to throw errors in these files because the system compiler doesn't
understand __attribute__.
Issue reported by Kazuo Kuroi <kazuo at irixnet dot org>.

John Gardner: handling of ASCII control characters during input

Manually tag the section option.
Automatic tagging does not work because the [-s] flag is optional.
Patch from Martin Vahlensieck.

Sync stringlist implementation with NetBSD.
Various improvements of security, functionality, and style.

sync with OpenBSD, no functional change intended

update millert@'s email address

document -T html -O tag as implemented in main.c rev. 1.350

Support -T html -O tag by passing a file:// URI to the pager.
Feature suggested by and implementation based on a patch
from Abel Romero Perez <romeroperezabel at gmail dot com>.

add missing compat_stringlist.o to ALL_COBJS, useful for make clean

Only compile compat_*.c implementations that are actually needed.
That's cleaner and it is supposed to fix compiler warnings with gcc 10
reported by Wynn Wolf Arbor <wolf at oriole dot systems> on discuss@.

Make the ./configure script simpler, more robust, and 23 lines shorter:
* three rather than four arguments for singletest()
* let runtest() support testing two variants of compiler flags
* always report a failed test, even when another test follows
* run all tests before detecting fatal conditions
* rename HAVE_CMSG_XPG42 to NEED_XPG4_2 for consistency
* consistently use braces for shell variable interpolation
* drop archaic "X${" syntax and unusual "==" in string comparisons

merge rev. 1.58 from OpenBSD (deraadt@):
recallocarray() the string buffer, to avoid leaving such contents
around in the address space.  Don't bother doing so for the buffer
which contains aslr'd pointers...
OK millert@

Give the fts_compar struct member a real prototype.
This adds clarity and avoids compiler warnings.

Fix a regression in rev. 1.319 (2019/03/03):
Pass the right object to html_reset() or it will crash
when rendering more than one manual page to HTML in a row.
Bug reported by Abel Romero Perez <romeroperezabel at gmail dot com>.
Patch from otto@.

While we do not recommend the idiom ".Fl Fl long" for long options
because it is an abuse of semantic macros for device-specific
presentational effects, this idiom is so widespread that it makes
sense to convert it to the recommended ".Fl \-long" during the
validation phase.  For example, this improves HTML formatting
in pages where authors have used the dubious .Fl Fl.

Feature suggested by Steffen Nurpmeso <steffen at sdaoden dot eu>
on freebsd-hackers.

Resurrect the documentation of the print_otag() 's' attribute specifier,
reverting a minor part of rev. 1.21.  Contrary to what i thought, that
attribute *is* still supported for a small number of unusual cases.

provide a STYLE message when mandoc knows the file name and the extension
disagrees with the section number given in the .Dt or .TH macro;
feature suggested and patch tested by jmc@

In fragment identifiers, use ~%d for ordinal suffixes,
and reserve the character '~' for that purpose.

Bug found by validator.w3.org in openssl(1), which contains both a
tag "tls1_2" and a second instance of a tag "tls1", which also resulted
in "tls1_2", causing a clash.  Now, the second instance of "tls1" is
rendered as "tls1~2" instead, employing the newly reserved '~'.

When .Bd, .D1, or .Dl is tagged, attach the permalink
to the first few letters, similar to what was earlier done for .Pp.

Correctly handle non-unique tags even when NODE_ID and NODE_HREF fall
apart, NODE_ID occurring earlier than NODE_HREF.

Major update:
Complete includes, add several functions, no more <?xml?>,
no more style attributes, NODE_HREF flag, mention roff_html.c.

When a .Tg is attached to a paragraph, attach the permalink
to the first word, or the first few words if they are short.

Use a separate node->tag attribute rather than abusing the node->string
attribute for the purpose.  No functional change intended.
The purpose is to make it possible to later attach tags to text nodes.

Separate the place to put the <a href> permalink (now marked
with NODE_HREF) from the target element of the link (still marked
with NODE_ID).  In many cases, use this to move the target to the
beginning of the paragraph, such that readers don't get dropped
into the middle of a sentence.

Support manual tagging of .Pp, .Bd, .D1, .Dl, .Bl, and .It.
In HTML output, improve the logic for writing inside permalinks:
skip them when there is no child content or when there is a risk
that the children might contain flow content.

automatically tag .SH and .SS in man(7) terminal output
in the same way as it was done for .Sh and .Ss in mdoc(7)

Remove some stray argument names from function prototypes,
for consistency with the dominant style used in mandoc.
No functional change.
Patch from Martin Vahlensieck <academicsolutions dot ch>.

#include <stdint.h> because that is needed before #include <ohash.h>;
fixing a build failure of mandoc-portable on Arch Linux
reported by Stephen Gregoratto <dev at sgregoratto dot me>.

When the last file formatted yielded no tags, the tags file got
deleted before starting the pager, even when earlier input files
had written to it; thanks to weerd@ for reporting that bug.

Since we now generate tags for section headers, we almost always
generate at least some.  Consequently, while fixing the above bug,
simplify the code by never deleting the tags file before the pager
exits, not even in the rare case that the file happens to be empty.
Hence, this patch is -75 +63 LOC even though it fixes two bugs.

While deleting the output files belongs after exit from the pager,
closing them should be done before it is started.  Collect the
related code, which was scattered in various places, to where
it belongs, in a dedicated function in the term_tag.c module.
As a side benefit, never fclose(2) stdout, only dup2(2) to it.

Similarly, when the -O tag argument wasn't found in the last file
formatted, there was a complaint about "no such tag" even when the
argument did occur in earlier files.  Fix that by looking for a
matching tag after every formatted file rather than just once at
the very end.  Given that command line arguments aren't properties
of the file(s) being formatted, that check is a job for the main
program, not for the formatters, so while fixing the check, move
it from term_tag.c to main.c.

Copy tagged strings before marking hyphens as breakable.
For example, this makes ":tCo-processes" work in ksh(1).

Just like we are already doing it in HTML output, automatically tag
section and subsection headers in terminal output, too.  Even though
admittedly, commands like "/SEE" and "/   Subsec" work, too, there
is no downside, and besides, with the recent improvements in the
tagging framework, implementation cost is negligible.

Even though the HTML, man, markdown, PDF, PostScript, and tree formatters
never write a ctags(1) file, using a pager still requires writing the
main output file and passing the file name to the pager.
Recent regression mentioned on IRC and reported by kn@.

test skipping of initial hyphens and minus signs in automatic tags;
related to tags.c rev. 1.30

When setting automatic tags, skip initial hyphens and minus signs,
bringing the behaviour for mdoc(7) closer to what is already done
for man(7).
Triggered by the observation of kn@ that automatic tagging didn't
work very well for find(1) primaries.
OK kn@

The tag file always needs to be closed before starting the pager,
even when no output formatter was allocated because all pages
shown were preformatted.  Regression in previous reported
by <Andreas dot Kahari at abc dot se> on bugs@.

Make the "make depend" maintainer target more convenient
by having it run ./configure with native fts and ohash disabled.

Properly reset the validation part of the tagging module between files.
This fixes a crash in makewhatis(8) encountered by naddy@.

Split tagging into a validation part including prioritization
in tag.{h,c} and {mdoc,man}_validate.c
and into a formatting part including command line argument checking
in term_tag.{h,c}, html.c, and {mdoc|man}_{term|html}.c.

Immediate functional benefits include:
* Improved prioritization of automatic tags for .Em and .Sy.
* Avoiding bogus automatic tags when .Em, .Fn, or .Sy are explicitly tagged.
* Explicit tagging of .Er and .Fl now works in HTML output.
* Automatic tagging of .IP and .TP now works in HTML output.
But mainly, this patch provides clean earth to build further improvements on.

Technical changes:
* Main program: Write a tag file for ASCII and UTF-8 output only.
* All formatters: There is no more need to delay writing the tags.
* mdoc(7)+man(7) formatters: No more need for elaborate syntax tree inspection.
* HTML formatter: If available, use the "string" attribute as the tag.
* HTML formatter: New function to write permalinks, to reduce code duplication.

Style cleanup in the vicinity while here:
* mdoc(7) terminal formatter: To set up bold font for children,
defer to termp_bold_pre() rather than calling term_fontpush() manually.
* mdoc(7) terminal formatter: Garbage collect some duplicate functions.
* mdoc(7) HTML formatter: Unify <code> handling, delete redundant functions.
* Where possible, use switch statements rather than if cascades.
* Get rid of some more Yoda notation.

The necessity for such changes was first discussed with kn@, but i didn't
bother him with a request to review the resulting -673/+782 line patch.

The HTML standard does not allow self-closing syntax for non-void elements.
Consequently, write an explicit end tag for <mark> elements.

Fully support explicit tagging of .Sh and .Ss.
This fixes the offset of two lines in terminal output
and this improves HTML output by putting the id= attribute
and <a> element into the respective <h1> or <h2> element rather
than writing an additional <mark> element.

To that end, introduce node flags NODE_ID (to make the node a link
target, for example by writing an HTML id= attribute or by calling
tag_put()) and NODE_HREF (to make the node a link source, used only
in HTML output, used only to write an <a class="permalink"> element).

In particular:
* In the validator, generalize the concept of the "next node"
such that it also works before .Sh and .Ss.
* If the first argument of .Tg is empty, don't forget to complain
if there are additional arguments, which will be ignored.
* In the terminal formatter, support writing of explicit tags
for all kinds of nodes, not just for .Tg.
* In deroff(), allow nodes to have an explicit string representation
even when they aren't text nodes.  Use this for explicitly tagged
section headers.  Suprisingly, this is sufficient to make HTML
output work, without explicit code changes in the HTML formatter.
* In syntax tree output, display NODE_ID and NODE_HREF.

Introduce the concept of nodes that are semantically transparent:
they are skipped when looking for previous or following high-level
macros.  Examples include roff(7) .ft, .ll, and .ta, mdoc(7) .Sm
and .Tg, and man(7) .DT and .PD.  Use this concept for a variety
of improved decisions in various validators and formatters.

While here,
* remove a few const qualifiers on struct arguments that caused trouble;
* get rid of some more Yoda notation in the vicinity;
* and apply some other stylistic improvements in the vicinity.

I found this class of issues while considering .Tg patches from kn@.

Fix this test after the recent Unicode update in OpenBSD base.
The test uses U+07FF NKO TAMAN SIGN because it is the highest
code point having a two-byte UTF-8 representation.
This character is a new single-width punctuation character in
Unicode 11, such that mandoc now does correct horizontal spacing.
We already used the code point for the test before it was assigned,
which resulted in weird spacing because wcwidth(3) returns -1 for
unassigned code points.

Marc Espie reported that "man p*ipc" displayed the perlipc(1) manual.
The reason was that as a last resort when failing to find a page
name in mandoc.db(5) or at a few well well-defined fully qualified
file names, man(1) uses glob(3) to look for candidate files in
relevant directories, because some operating systems have weird
file name extensions, for example pcap.3pcap and BF_set_key.3ssl
on Linux.  But during that globbing, the metacharacters "*?[" need
to be escaped in the name, section, and path supplied by the user,
or you would get weird false positives and misleading warning
messages and would be unable to use the fallback for path or file
names that actually contain an opening bracket.
Feedback and OK espie@.

bugfix: indented paragraph macros need a space character
before the width argument

bugfix: .Tg must be ignored completely in these output modes

Mention that .AT, .P, .SB, and .UC are extensions; it really matters
because we only retain the language for backward compatibility in
the first place.  Part of the research done by <G dot Branden dot
Robinson at gmail dot com>, see the list <groff at gnu dot org> for
details.

No change to the following conventions: Consider portable whatever
made it into GNU troff no later than 4.4BSD.  For portable extensions,
mention their origin at the end of the description.  For non-portable
extensions, for example from man-ext, usually warn earlier, near
the beginning of the description.

mention that -T man does not support eqn(7) and tbl(7);
triggered by a question from Stephen Gregoratto <dev at sgregoratto dot me>

two new entries: "Fl Fl" to "Fl \-" in validation and eqn/tbl in -T man

Mention that the .Dd "date" argument is the date of the last change.
Triggered by a question from Jason A. Donenfeld.

While here, delete three COMPATIBILITY entries that i fixed some time ago.

Digit-width and narrow spaces are non-breaking.
Noticed because Branden Robinson worked on related documentation in groff.

In roff, a space character at the beginning of an input line requires
starting a new output line, and merely starting a new line of HTML
code isn't sufficient to achieve that.  Solve this in the same way
as mdoc_html.c already does it, by printing a <br/> element.
Fixing a bug reported by Jason A. Donenfeld <Jason at zx2c4 dot com>
in the wg-quick(8) manual page on manpages.debian.org.

Finally delete support for the "_whatdb" configuration directive,
which has a misleading syntax.  It was declared obsolete and
superseded by the "manpath" directive five years ago.

Reduce the diff to OpenBSD by making FILES a list,
even though it has only one entry in the portable version.
Do not add /etc/examples/man.conf for the portable version, though.

The man(1) command was already available in AT&T Version 2 UNIX.
Jonathan Gray found it in the "Combined Table of Contents" in Doug
McIlroy's "A Research UNIX Reader", which contains a table of which
edition manuals appeared in, and in both the "Table of Contents"
(page vi) and the body (page 89) of the printed UNIX Programmer's
Manual (June 12, 1972) from bitsavers.

For compatibility with the man(1) implementations of the man-1.6
and man-db packages, print the manpath if the -w option is given
without a following name argument.

This quirk has been in man-1.6 since at least man-1.5e (1998)
and in man-db since 2012.

Using this feature in portable software is a dubious idea because the
internal organization of manual page directories varies in about a
dozen respects among operating systems, so even if you get the answer,
there is no portable way to use it for looking up anything inside.
However, Matej Cepl <mcepl at suse dot cz> made me aware that some
software, for example the manual viewing functionality in the newest
editors/neovim code, unwisely relies on this feature anyway.

No objections were raised when this patch was shown on tech@.

Make sure that -l always causes -w to be ignored, as documented
in the man(1) manual page.  This bugfix is needed to prevent
the command "man -lw" from dereferencing a NULL pointer.