mdoc(7): improve output of .At 32v

The official designation by AT&T was "UNIX/32V", so use that in the output.
That also makes sense because "system/architecture" is a widespread
convention to refer to the port of an operating system to a specific
architecture, in this case 32V (32bit DEC VAX).

The former wording "Version 32V AT&T UNIX" was misleading
because 32V is not a version number.

Even though UNIX/32V was not officially designated as Version 7 by AT&T,
prepend "Version 7" because it was in fact a straightforward port of
Version 7 AT&T UNIX.  That makes it easier to understand for 21st
century readers of manual pages.

Suggested by nabijaczleweli at nabijaczleweli dot xyz.
Same change as in GNU troff commit 21d30728.
OK  G dot Branden dot Robinson at gmail dot com  (gbranden@ in groff)

In the fallback code to look for manual pages without using mandoc.db(5),
accept files "man<one-digit-section>/<name>.<full-section>"
in addition to the already supported "man<full-section>/name.[01-9]*".
Needed for example on Alpine Linux which puts its Perl manuals
into "man3/<name>.3pm" and the POSIX manuals into "man3/<name>.3p".

While here, allow the glob(3) at the end of fs_lookup() to add multiple
matches to the result set.  This improves man -w output and may also
help some cases of plain man(1), allowing main() to prioritize properly
rather than fs_lookup() picking a random match.

Issue reported and patch tested
by Soeren Tempel <soeren at soeren hyphen tempel dot net>.

do not crash when a manpath directory contains a symbolic link
that points to a directory rather than to a regular file;
bug reported by Lukas Epple <sternenseemann at systemli dot org>,
and my patch also tested by him on NixOS

fix the section number in the <title> element for preformatted pages;
minibug reported by Ian <Ropers at gmail dot com> on misc@

print a BAGARG message if -T markdown is requested on man(7) input;
suggested by Michael Stapelberg at debian dot org

Support two-character font names (BI, CW, CR, CB, CI)
in the tbl(7) layout font modifier.

Get rid of the TBL_CELL_BOLD and TBL_CELL_ITALIC flags and use
the usual ESCAPE_FONT* enum mandoc_esc members from mandoc.h instead,
which simplifies and unifies some code.

While here, also support CB and CI in roff(7) \f escape sequences
and in roff(7) .ft requests for all output modes.  Using those is
certainly not recommended because portability is limited even with
groff, but supporting them makes some existing third-party manual
pages look better, in particular in HTML output mode.

Bug-compatible with groff as far as i'm aware, except that i consider
font names starting with the '\n' (ASCII 0x0a line feed) character
so insane that i decided to not support them.

Missing feature reported by nabijaczleweli dot xyz in
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=992002.
I used none of the code from the initial patch submitted by
nabijaczleweli, but some of their ideas.
Final patch tested by them, too.

Rename the compile-time configuration variable $HOMEBREWDIR to
$READ_ALLOWED_PATH, allow it to contain more than one directory,
and explain how to use it for NixOS and for GNU Guix Linux.

Feature improvement based on observations, input, and earlier patches
from Lukas Epple <sternenseemann at systemli dot org>, and final
patch also tested by Lukas.

.OP is not a GNU extension but first appeared in the Documenter's Workbench,
see https://github.com/n-t-roff/DWB3.3/blob/master/macros/man/an.sr#L33

from g dot branden dot robinson at gmail dot com
via GNU troff commit e3459327 2 Aug 2021 10:49:46 -0400

manually tag the macro names that have false positives

Improve the description of .Fl in multiple respects and in paricular
improve the .Fl examples in multiple respects, including better
demonstrating long options.
Prompted by a question from espie@.
Feedback and OK jmc@.

Support auto-tagging for ".It Va".

This combination is somewhat rare because few libraries expose so many
global variables that they need a list to enumerate them, but when the
idiom does occur, tagging the variable names is generally useful.
For example, this helps awk(1), dc(1), make(1), rc.subr(8), ...

Missing feature reported and patch reviewed, tested, and OK'ed by kn@.

s/The arguments are as follows:/The options are as follows:/
because that's what the example is talking about;
patch from kn@

The mandoc(1) manual already mentions that -T man output mode
neither supports tbl(7) nor eqn(7) input.
If an input file contains such code anyway, tell the user
rather than failing an assert(3)ion.

Fixing a crash reported by Bjarni Ingi Gislason <bjarniig at rhi dot hi dot is>
in https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=901636 which the
Debian maintainer of mandoc, Michael at Stapelberg dot ch, forwarded to me.

delete the two pairs of extra blank lines from expected man(7) terminal
output that are no longer printed since man_term.c rev. 1.236

In terminal output of man(7) documents, stop printing two extra blank
lines before the NAME section and before the page footer.  While these
blank lines had a long tradition, they didn't really serve any purpose
and merely wasted screen real estate.  Besides, this makes output from
man(7) more similar to output from mdoc(7).

This commit keeps mandoc compatible with groff-current,
where G. Branden Robinson committed the same change
on June 16 (groff commit 2278d6ed).

add a style message about overlong text lines,
trying very hard to avoid false positives,
not at all trying to catch as many cases as possible;

feature originally suggested by tb@,
OK tb@ kn@ jmc@

new TODO entry: HTML formatting of .nf

three new TODO items

In -W style mode, check .Xr links along the full manpath because
that is more useful for validating manuals of non-base software.
Nothing changes in -W all mode: by default for -T lint, we still
assume we want to check base system conventions, including usually
not wanting to link to non-base manual pages.

The use case, a partial idea how to handle it, and a preliminary
patch was originally presented by kn@, then refined by me.
Final patch tested and OK'ed by kn@.

tbl(7) layout "n" specifier for HTML output

In revision 1.157 of cgi.c, a meta viewport element was added to
the HTML output.  Let `mandoc -Thtml' behave the same, making the
generated HTML a bit more pleasant to view on a mobile device.
Patch from anton@.

test private use areas some more as they have proven fragile

Cleanup:
1. Move invalid two-byte sequences after valid ones
and make their descriptions easier to understand.
2. Replace the wrong and confusing expression "middle byte"
with the correct term "start byte".
3. Add test lines for U+EFFFF and U+F0000.
4. Replace the unhelpful word "strange" with more descriptive terms.
Arguably, nothing about this (or maybe everything?) is strange.

The wcwidth(3) of Plane 15 and Plane 16 Private Use Characters
was changed from 0 to 1. Adjust the test results accordingly.
Issue reported by bluhm@

When looking for column separators on tbl(7) data lines, properly skip
escape sequences; do not misinterpret bytes from the middle of escape
sequence names or arguments as column separators.
Bug reported and patch tested by Oliver dot Corff at email dot de.

Implement the layout specification "a" (left justify with 1em indentation)
in HTML output mode; before this patch, the indentation was missing.
Terminal output already supported the "a" specifier since 2010.
Issue reported and patch tested by Oliver dot Corff at email dot de.

test font modifiers in the layout; related to tbl_html.c rev. 1.34

implement the tbl(7) layout modifiers "b" (bold) and "i" (italic)
in HTML output mode, similar to tbl_term.c, function tbl_word();
issue reported by Oliver dot Corff at email dot de

When looking for the last layout row used, we need to look at the layout
row used for the previous data line containing data, not at the previous
data line outright, which might be a horizontal ruler.  If it is, do not
restart from the first layout row but still proceed to the next data row,
which may have been just read from T&.

Bug originally reported by Oliver dot Corff at email dot de
on groff at gnu dot org:
https://lists.gnu.org/archive/html/groff/2021-03/msg00003.html
and forwarded to me by bentley@.

Patch OK'ed by bentley@ back in April.

Add OpenBSD riscv64 architecture; patch from jsg@.
While here, retire sgi and socppc.

remove stray byte from broken escape sequence; diff from jmc@

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.