Delete support for the style=text-indent attribute, which is no longer used.

For -man -Thtml, ignore author-specified .HP widths because they
harm responsive design; use @media-dependent defaults instead.

Revert previous: style=height is still used by roff_html.c, and it
doesn't actually harm responsive design, so keep it for now.
Bug reported in de.comp.os.unix.bsd via naddy@, thanks.

delete support for the HTML style=height property, which is no longer used

In HTML output, for lists that have an -indent argument, just use
a uniform indentation in CSS adapted to the viewport width and
ignore the value of the argument taken from mdoc(7).  While
author-specified widths somewhat work as a micro-optimization in
terminal and typeset output, they are nothing but harmful in HTML
style= attributes because they break responsive design, whereas
using a reasonable default indent almost never results in ugly
output.  Admittedly, the author-specified width might occasionally
look even better, but only slightly so, and only for some viewport
sizes.
Based on guidance provided by John Gardner.

When formatting man(7) documents that do not contain .SH macros
with -Tps or -Tpdf, do not squeeze the whole text beyond the right
margin.  Bug reported by Will Backman during BSDCan.

Remove redundant value= attributes from option elements,
and use type=search rather than type=text for the input element
because it tends to better support autocompletion.
Both suggested by John Gardner <gardnerjohng at gmail dot com>.

Delete support for the print_otag(sw) * and - modifiers,
which are no longer used because we write fewer style= attributes.

Ignore author-specified -width arguments for -tag and -hang lists
in HTML output.  For terminal and typeset output, such arguments
kind of work to achieve presentational micro-optimization.
But for HTML, they only do harm.

Large increases usually look ugly.  Large reductions are impossible
since the default is not large in the first place.  Small tweaks in
either direction are not important; at least not important enough
to justify making responsive design impossible.

Triggered by John Gardner's suggestion to further reduce style=
attributes in the HTML code, in particular those containing hard-coded
lengths.

John Gardner tells me that among frontend developers, gratuitous use
of double selectors like "element.class" is considered poor style.
When doing selection mainly by elements is not appropriate because
most elements require several different styles, exclusively selecting
by class is less cumbersome, more concise, and more flexible.
So drop the elements from the selectors, except where they are
required for disambiguation and except where they add clarity due
to the presence of child selectors.

URL-fragment strings can only contain certain characters.
Fixing HTML syntax violations e.g. in pf.conf(5) and ifconfig(8)
reported by Anton Lazarov <lists at wrant dot com>.

Start with baby steps towards responsive design:
Use a @media width query to select a set of default indentations.
Suggested by John Gardner <gardnerjohng at gmail dot com>.

Use em units rather than ex units for horizontal lengths.
John Gardner and others tell me it produces more predictable results
and is generally considered better style.
Also use 0em instead of 0ex, in general.

Do not write duplicate id= attributes, they violate HTML syntax.
Append suffixes for disambiguation.  Issue first reported by Jakub
Klinkovsky <j dot l dot k at gmx dot com> (Arch Linux).

Use <span> for .Ms rather than <b>; discussed with John Gardner.

Use <span> for .Ad rather than <i>; also suggested by John Gardner.

Use <span> rather than abusing <i> for .Pa;
suggested by John Gardner <gardnerjohng at gmail dot com>.

various minor improvements

Protect against malicious manual pages containing .ll requests with
excessive arguments: apply the same cutoff as for the -O width=
command line argument.

While here, also place some assertions at strategical places to
prevent excessive indentations from being printed in case of bugs.
In the past, we had more than one bug that caused mandoc to print
effectively infinite output, filling up people's /tmp/ file system,
which is not funny.  We cannot prevent bugs from crashing the
program, but we can at least make filling up the disk less likely.

Triggered by a remark from sthen@ on source-changes@.

In a nutshell, all mobile browsers are broken.
By default, no matter the physical screen size, they use a fixed
viewport width of about 1000px, then scale down the rendered page
to make that huge viewport fit on the physical screen.
That results in poor rendering for bad websites which assume a
large fixed-size viewport (typically requiring zooming in to be able
to actually read any text), but in atrocious rendering for good
websites that make no assumption about the screen size (unreadably
small text in the top left corner, most of the screen empty).

A standard way to disable that insane behaviour and just render
normally on the actual physical screen size does not exist.
The closest thing is the CSS3 Device Adaptation Module Level 1
https://drafts.csswg.org/css-device-adapt/
but https://caniuse.com/#feat=css-deviceadaptation tells me
that basically no browser implements it, not even on mobile.

The next closest thing is the HTML meta viewport element - even though
the problem has nothing to do with HTML and is purely a CSS issue.
Standardization is not even planned for that one:
* HTML 5.2 mentions it in passing without specifying it:
https://www.w3.org/TR/html/document-metadata.html#the-meta-element
* The Web Hypertext Application Technology Working Group
provides very incomplete information:
https://wiki.whatwg.org/wiki/MetaExtensions
* CSS3 Device Adaptation Module Level 1 already wants to deprecate it,
explaining mostly how to migrate *away* from it to some castle in
the sky that no browser implements:
https://drafts.csswg.org/css-device-adapt/#viewport-meta

While i strongly believe in sticking to well-established standards,
in the absence of standards and with atrocious behaviour being
universal, there appears to be no alternative to using whatever
works.  The meta viewport element appears to be the only way to
make real-world mobile browsers decently render any HTML page that
does not have a fixed-width layout of 1000px.  So use it, grudgingly.

Originally suggested by xcv at dr dot com.
Direction supported by espie@.

Some broken terminal emulators (e.g. sakura) do the equivalent
of "stty cols 0".  Ignore that insanity rather than setting
conf.output.width to an invalid value and embarking on infinite loops.
Issue reported by Jesper Wallin <jesper at ifconfig dot se>, thanks!

Fix a long-standing issue:
Some macros (Nd, Oo) can contain blocks but rendered as elements that
can only contain phrasing content, resulting in invalid HTML nesting.
Switch them to <div>.
Also move the related "display: inline" style from the HTML to the CSS.

Reminded during a conversation with John Gardner.

Eliminate the class=It-* attributes.
Cleaner HTML, more idiomatic CSS, and minus 30 lines of C code.
Suggested by John Gardner <gardnerjohng at gmail dot com>.

Switch the emitted HTML element from <b> to <code> for the fixed
syntax element macros .Nm, .Fl, .Cm, .Ic, .In, .Fd, .Fn, and .Cd.
Adjust both the internal and external style sheets such that
rendering remains unchanged in typical browsers.

Based on feedback from John Gardner <gardnerjohng at gmail dot com>.

Minor correction: we render HTML character references hexadecimal,
not decimal; bentley@ changed that in html.c on July 14, 2017.

skip printing the embedded style sheet if an external style is referenced

Simpler description of output formats, shortening the manual page by 15 lines.
Avoid the double redirection from -Tutf8 via -Tlocale to -Tascii.
Add LC_CTYPE to the ENVIRONMENT section.
While here, also correct a few inaccuracies and tweak some wordings.
Triggered by a question from Laura Morales <lauretas at mail dot com>.

Better mandoc(1) -I and -T options for Heirloom comparisons.
Filter through col(1) -b for Heirloom because it produces double encoding.
Switch on mandoc(1) -Wall in groff comparisons.
Update usage.

multiple new entries from various sources

replace my vague and idiosyncratic term "selflink"
with the clearer and more usual "permalink";
suggested by John Gardner <gardnerjohng at gmail dot com>

dedup issues

Tweak the description of -l:

Avoid the misunderstanding that the essential purpose of -l is
similar to the purpose of the -a option in mandoc(1), which is not
the point: the fact that -l implies -a is merely a minor detail.
The point of -l is to make man(1) behave like mandoc(1).
Move the mention of -a to the end to de-emphasize it.

Nate Bargmann reported that this seriously confused him,
and i can see why.

Compatibility with man-db:
In page name mode (= man(1) default mode), also try to interpret
names containing slashes as absolute or relative file names.

Missing feature reported by Nate Bargmann on <groff at gnu dot org>,
and the man-db maintainer Colin Watson <cjwatson at debian dot org>
kindly explained to me how this is supposed to work.

Use TIOCGWINSZ to reduce the default -Owidth during interactive use
on terminals narrower than 79 columns and the default -Oindent on
terminals narrower than 66 columns.
Requested by and feedback from pirofti@;
mpi@ and juanfra@ also like the general direction.

Make sure that mandoc only goes into UTF-8 mode if the user really
selected UTF-8, not some other multibyte locale.  This obviously
makes no difference on OpenBSD but improves portability.
Issue reported by <Nakayama at NetBSD> via wiz@.

preserve comments before .Dd and .TH (typically Copyright and license)
in full HTML output, but not with -Ofragment, e.g. in man.cgi(8);
suggested by Thomas Klausner <wiz at NetBSD>

preserve comments before .Dd when converting mdoc(7) to man(7)
with mandoc -Tman; suggested by Thomas Klausner <wiz at NetBSD>

Two new low-level roff(7) features:
* .nr optional third argument (auto-increment step size)
* \n+ and \n- numerical register auto-increment and -decrement
bentley@ reported on Dec 9, 2013 that lang/sbcl(1) uses these.

When accessing an undefined number register, define it to be zero, like
the previous commit for strings and macros, only technically simpler.
Desired behaviour also mentioned by Werner Lemberg in 2011.
This diff adds functionality but is -21 +19 LOC.  :-)

Using an undefined string or macro will cause it to be defined as empty.
Observed by Werner Lemberg on Nov 14, 2011
and rotting on my TODO list ever since.

Stop documenting the non-portable .R man(7) macro.  Neither groff
nor the heirloom-doctools support it.  Adding it was a mistake in
the first place.

Do not use a non-portable .R man(7) macro.  Neither groff nor the
heirloom-doctools support it.  Work around the gap by using .BR
with an empty first argument.  This was noticed more than once in
the past, but i always forgot to fix it.

use the portable \(lq and \(rq internally rather than \(Lq and \(Rq

For .Do/.Dq, use the documented and portable \(lq and \(rq
character escape sequences rather than the undocumented and
non-portable \(Lq and \(Rq.

Bug reported by Tim L <darkxst at github>
via Thomas Klausner <wiz at NetBSD>;
see https://github.com/nih-at/libzip/pull/42

Ouch, fix previous:  In the edge case of a single-character string
containing nothing but a single hyphen, the pointer got incremented
twice at one point, causing a read overrun found by naddy@.

Style message about bad input encoding of em-dashes as -- instead of \(em.
Suggested by Thomas Klausner <wiz at NetBSD>; discussed with jmc@.

Soften the language discouraging special character escape sequences.
After i improved their ASCII renderings in groff and mandoc some time
ago, mathematical symbols can now be used in specialised mathematical
manual pages like libm and some X libraries.
Tweaks and OK jmc@.

Add strndup(3) compat implementation.
Jan Stary reports that MacOS X Snow Leopard and older lacks it.

After opening a file with gzdopen(3), we have to call gzclose(3) or
we leak memory internally used by zlib to keep compression state.
Bug reported by Wolfgang Mueller <vehk at vehk dot de> who also
provided an incomplete patch, part of which i'm using in this commit.

clarify documentation of macro keys

Logically, the following are are type names - just like .Vt,
some of them with an optional variable name following:
- .Ft
- .Fa in the SYNOPSIS
- .Fn second and later arguments in the SYNOPSIS
So add these to the .Vt macro table in the mandoc.db(5) database.
During my LibreSSL work, i'm getting really tired of typing
$ man -k Vt,Ft,Fa=some_type_name
over and over again; now, this becomes just:
$ man -k Vt=some_type_name

Invalidate the tag_files.tfd after fclose(3)ing the stram associated
with it.  In main() assert that the tfd was actually invalidated.
This avoids closing an invalid fd.
From tb@; OK deraadt@ on an earlier version.

In man(7) and cat pages, cut off excessive one line descriptions.
An extreme example of how rogue files could mess up apropos(1) output
was reported by bentley@: qwtlicense(3) in the x11/qwt port.

Fix the mandoc_strndup() utility function.  All existing callers seem
safe so far, but implementing it with an unchecked memcpy(3) is just
wrong and quite dangerous.

fix wrong date

Delete the "no blank before trailing delimiter" check from the
partial explicit macros.  Leah Neukirchen <leah at vuxu dot org>
rightfully points out that the check makes no sense for these macros.

Remove the implicit display feature of .Lk because it was inconsistent
across output devices, counter-intuitive, and resulted in ugly
output for many real-world manual pages.  Always format even long
links in-line.  I already committed a similar change to groff.

OK jmc@, bentley@, and the original author
of the feature, Werner Lemberg <wl@gnu.org>.

typo; from Alexander Kuleshov <kuleshovmail at gmail dot com>

Recognize .Bl -column at parse time, and not only at validation time,
even if other arguments precede -column.  This is required because
the .It parser needs to know whether or not we are a -column list.
Fixes tree corruption leading to an assertion failure.
Bug reported by bentley@.

duplicate word, found by igor(1)

streamline termp allocation: this will allow the init function
to do things differently in the ps vs pdf case;
from espie@

be less assertive when warning about a possible typo;
from jca@, ok jmc@

Shrink -Tps output by more than 50%
by using PostScript as a programming language.
* Define and use one PostScript procedure to select each font.
* Define and use procedures combining "use" and "show".
* In one of these, reuse the current row if it did not change.
Most ideas and most coding by espie@, tweaked by me.

Print a human-readable media name in the %%DocumentMedia DSC comment
and use the setpagedevice PostScript operator to help printers
automatically select the paper of the best matching PageSize.

Many thanks to Mike Williams <obsd1 at eandem dot co dot uk>
for teaching me about the relevant features of PostScript and DSC
and for suggesting what to put into the first %%DocumentMedia argument.

duplicate anchors

more readable conversion of paper size from millimeters to PostScript
basic units, also slightly more precise

The page footer line (psmarg) is created in ps_begin(), and the
last call writing to it is always ps_endline(), which ends with
ps_pclose(), which prints "ET" (end text).

Consequently, do not print another instance of "ET" in ps_closepage()
after the footer line and before the "endstream" for the page.

Fixing a PDF syntax error found while investigating the bug report
from Jan Stary that also resulted in the previous commit.

Properly close out the top-level Font object, the end-of-page
Resource objects, and the Catalog object, fixing three PDF syntax
errors that were present in every PDF file generated with mandoc
since the initial checkin of the formatter in July 2010.
Bug reported by Jan Stary <hans at stare dot cz> on misc@.

Modernize documentation of .Ao and .Aq.

I looked through our whole tree and failed to find a single use
that is really convincing, except those with .Mt.  Putting it around
character and key names is somewhat widespread and maybe acceptable,
even if hardly useful.

So for now, delete the bogus examples and explain what these macros
are really used for.  Discourage the most common abuses.

Triggered by a question from Raf Czlonka <rczlonka at gmail dot com>.

HISTORY: mention first appearance in OpenBSD

Do not segfault when there are two .Dt macros, the first without
an architecture argument and the second with an invalid one.
Bug found by jsg@ with afl(1).

typo: convertion -> convention; from dcoppa@

fix a NULL pointer access on deroff() failure;
could be triggered with '.SS ""';
reported by Michael <Stapelberg at debian>

fix grammar; while here, improve spacing; from sobrado@

format ".IP *" etc. as <ul> rather than <dl>

Fix previous: mmap(2) returns MAP_FAILED on failure, not NULL.
Bug pointed out by tedu@.

Do not fork and exec cmp(1); instead, simply fstat(2), mmap(2), and
compare the files directly, allowing a much stricter pledge(2), at
very little cost: merely 15 additional lines of very simple code.
Suggested by George Brown <321 dot george at gmail dot com> on misc@.

No need to fork and exec rm(1) -rf, we know that we have exactly
one file and exactly one directory to remove.  While here, increase
the size of the buffer such that the file name actually fits.
Minus 17 lines of code, no functional change.

Opportunity for simplification reported by George Brown <321 dot
george at gmail dot com> on misc@.

remove spacing after another representation of unary minus

remove spacing after unary minus

eliminate white space after opening and before closing punctuation

use the tty-char macro file for ASCII comparisons

Suppress spacing before certain kinds of lists.
One benefit is a reduced probablity that a blank appears between
a function name and the opening parenthesis introducing the arguments.
The heuristics isn't perfect and may occasionally suppress a blank
that wouldn't do harm.

Improve ASCII rendering of a few rare character escape sequences
that can be changed unilaterally because groff fails to render them
at all.

catch up with ASCII renderings in chars.c rev. 1.72

Switch ASCII rendering of the same mathematical symbols and greek
letters as in groff commit babca15f from trying to imitate the
characters' graphical shapes, which resulted in unintelligible
renderings in many cases, to transliterations conveying the characters'
meanings.  One benefit is making these characters usable for portable
manual pages.

Solving a problem pointed out by bentley@.

Correct the mandoc.db(5) requirements of man(1) after the deprecation
of MLINKS.  Inaccuracy pointed out by espie@.

When finding a bogus database entry,
print a meaningful warning and skip the entry.
Issue reported by espie@.

When the stdout stream gets broken, there is no point in reading
any more input files, and it would be misleading to start a parser,
because that would show randomly truncated text.
Instead, print an error message and exit the program.

Issue found by Leah Neukirchen <leah at vuxu dot org>, who was
surprised to see half a manpage when her /tmp/ overflew.

sync with FreeBSD;
suggested by Sevan Janiyan <venture37 at geeklan dot co dot uk>

Delete the lie that $PAGER would only be used with -a or -l; the text
was probably copied from mandoc(1) or apropos(1), where it is true.

document -O mdoc; triggered by a question from jmc@ and OK jmc@

Make the "new sentence, new line" check stricter, allowing digits
in the last two letters of the last word of the sentence.
No false positives in base or Xenocara.
Suggested by and OK jmc@.

Add two EXAMPLES; triggered by a question from jmc@.
Feedback and OK jmc@.

Explain how to transform markup for the terminal when not using a
pager, and how to remove markup.  Add related cross references.
While here, as suggested by jmc@, replace the excessive cross
references to the intro pages by a more relevant one to mandoc(1).
Triggered by a question from, using feedback from, and OK jmc@.

release 1.14.3

No longer use names that only occur in the SYNOPSIS section as names
for man(1) lookup.  For OpenBSD base and Xenocara, that functionality
was never intended to be required, and i just fixed the last handful
of offenders using it - not counting the horribly ill-designed
interfaces engine(3) and lh_new(3) which are impossible to properly
document in the first place.

Of course, apropos(1) and whatis(1) continue to use SYNOPSIS .Nm,
.Fn, and .Fo macros, so "man -k ENGINE_get_load_privkey_function"
still works.

This change also gets rid of a few bogus warnings "cross reference
to self" which actually are *not* to self, like in yp(8).

This former functionality was intended to help third-party software
in the ports tree and on non-OpenBSD systems containing manual pages
with incomplete or corrupt NAME sections.  But it turned out it did
more harm than good, and caused more confusion than relief,
specifically for third party manuals and for maintainers of
mandoc-portable on other operating systems.  So kill it.
Problems reported, among others, by Yuri Pankov (illumos).

OK jmc@

Ignore explicitly specified negative column widths rather than
wrapping around to huge numbers and risking memory exhaustion;
fixes Debian ps(1).  Bug reported by Dr. Markus Waldeck.

Fix an out of bounds read access to a constant array that caused
segfaults on certain hardened versions of glibc.  Triggered by .sp
or blank lines right before .SS or .SH, or before the first .Sh.
Found the hard way by Dr. Markus Waldner on Debian
and by Leah Neukirchen on Void Linux.

final tweaks for the 1.14.2 release