Support for Open/NetBSD's /etc/man.conf and others' manpath(1).
Most of this code (except the manpath part) written by schwarze@.
This isn't hooked into anything yet.

typo reported by Steffen Daode Nurpmeso <sdaoden at googlemail dot com>
and remove a trailing blank noticed by jmc@

Update historical record to be historical and not made-up.  Data from
<manpages.bsd.lv/history.html>.  Ok schwarze@ (with modifications) and
Jason McIntyre.

Initial support for man.conf/makepath(1).

Clarify some behaviour, bringing schwarze@'s patch and mine closer together
(although I still don't have -M, which is a big piece).

First, the default search path is the cwd.  This will change to use -M
once I look over that code.

If MANPATH is specified, this replaces the cwd.

Both of these are augmented by -m.

If paths don't exist or don't have databases, they're silently ignored.
This makes perfect sense: you may be given a superset of possible paths.
The corner case of no paths (where, say, MANPATH consists of bogus paths
or the cwd is unreadable) simply means that no paths are searched.

Ooops... tiny type error slipped in.

Integrate a moderately-patched version of schwarze@'s support for multiple
directories containing mandocdb(8) databases.  Some changes follow:

 (1) don't support -M yet;
 (2) fall back to cwd if no prior manpath has been specified;
 (3) resolve manpages using realpath() to prevent consecutive chdir()'s
     over relative paths;
 (4) note where further error-reporting is required;
 (5) fix leaking memory on exit in several cases.

Fix white-space in apropos_db.c to make merging cleaner.

Merge schwarze@'s work for 64-bit types.  This is based on a tweaked patch
submitted to tech@ on 16/11/2011, 01:39.  It has been updated to account
for the logical-operator functions and to avoid keeping a live pointer into
the DBT value, which is not guaranteed to be consistent across calls into
the bdb library.

Improve misleading comment:
* Not sure there were any text nodes, might have been other stuff instead.
* Not sure it was just one node, maybe several were deleted.
* No problem if some nodes were deleted, as long as some valid ones are left.
* We do not leave early, but after cleaning out all the crap.
* We are not "bailing", but we consider the block valid after cleanup.

Fix condition. Not enough tea.

Don't depend on snprintf to handle NULL strings. Deal with missing date.

Don't crash if the date can't be extracted. Don't depend on snprintf
handling NULL strings.

Slightly adjust last: return successful as some times the correct error
is raised later.

Convert an assert into an explicit check. man_unscope can be triggered
on unknown macros.

Bail out explicitly on invalid .Rs content like:
.Rs
plain text
.Re

This avoids a crash on invalid.

Evaluation with logical subexpressions.  This allows support for arbitrary,
nested logical subexpressions with AND (-a) and OR (-o) support.

using undefined macros or strings should define them to be empty

Guard mandocdb.h inclusion.

Correctly handle constructs like
.TP 8
.SH foo

Add lots of information about special characters that's actually needed
in practice, and discourage using fancy characters in manuals.
Text about "Dashes and Hyphens" by jmc@.
Feedback and ok jmc@, grudgingly ok kristaps@.

Have exprcomp() accept a string instead of an array-pointer.  Also, collapse
the arguments in apropos(1) into a single string passed to exprcomp().  Ok
schwarze@.

Make the man(7) page footer the same as in groff.

typo: overful -> overfull; thanks to jmc@

Make the default left text margin configurable from the command line,
just like the default right margin already is.  This may be useful for
people with expensive screen real estate.  Besides, it helps automated
man(7) to mdoc(7) output comparisons to validate -Tman output.
ok kristaps@ on an earlier version

Rewrite the expression parser for a more concise syntax:

 apropos [search_type[,...]=]substring
 apropos search_type[,...][,i]~regex

... and expression evaluation must take the search type into account.

This allows to:
* drop the global -I option and
* drop the enum match, just using a boolean int.

"go ahead" kristaps@

Inventing new keywords for mostly the same thing when a well-established
set of keywords already exists is a bad idea, so reuse the mdoc(7)
macro names as apropos(1) search types.  This is a gain in brevity
as well.  Some time ago, kristaps@ agreed in principle.

The search type bit field constants are used by both mandocdb(8) and
apropos(1) and should better stay in sync, so give them their own
header file.

Less misleading file names; ok kristaps@.

another detail to implement;
long live the tricky exceptions!

Fix two crashes that occur when walking very large (i.e. real-world) trees:
1) Avoid excessive, needless recursion, lest you overflow the stack;
2) Close all dir file descriptors, lest you run out of descriptors.
ok kristaps@

Use proper infix expressions and provide a default.  (Exact match.)

Make apropos's lookup use a find(1)-like expression.  I'll write more on
this when it completes; this is to keep it in-tree.

Right now this uses prefix notation.  Ignore it.  I'll make this into
infix notation real soon.

The goal of this (exprcomp and exprexec) is to have arbitrary logical
expressions.

Change getopt() to be more like schwarze@'s suggestions.

Split apropos.c into db.c and apropos.h with simpler code (re-written, but
inspired by apropos.c and mandoc-tools' mandoc-cgi.c).  This uses UTF-8
right now for its re-writing, but will soon accomodate for the regular
suspects (this is a rather simple matter).

I also introduce man.cgi (cgi.c), which is a standalone CGI that replaces
mandoc-tools' mandoc.cgi.  Right now it's just a framework.

Const-ify some mchars arguments.  I think these are non-const for historical
dumbness on my part.

When the HEAD scope of .TP is broken by another block macro,
do not abort with a FATAL error, but report a report a WARNING,
remove the broken .TP from the syntax tree, and prod on.
Reported repeatedly by ports people, at least by brad@ and jeremy@.
Also fixes rendition(4) in Xenocara.
ok kristaps@

Accomodate for \f(Cx formatting.  Noted by Andreas Vogele, thanks!

When .TH sets no data, leave the date field in the page footer blank,
do not use the current date.  This removes a gratuitous output difference
with respect to groff.
ok kristaps@

Correct .Eo spacing:
no space between the delimiters and the enclosed text.
The mdoc_html.c part was added by kristaps; ok kristaps@.

Clean up the description of .Dt:
- Volume and arch are both optional and not alternatives.
- Zap verbiage about what's obvious from the synopsis.
- For fixed argument strings, use .Cm, not .Ar.
Using lots of input from jmc@.

Also, state that the list of valid architectures varies by OS.
If a downstream distribution wants to provide a specific list,
maintaining a local patch is the way to go.

Implement missing enclosures (Ao Do Qo Qq So Bro Brq)
and enclosure-like in-line macros (Ad Cd Dv Er Ev Li Ms Tn).
The .No macro works without explicit implementation.

ok kristaps@

Handle infinite recursion the same way as groff:
When string expansion exceeds the recursion limit, drop the whole
input line, instead of leaving just the string unexpanded.

ok kristaps@

Handle \N numbered character escapes the same way as groff:
If \N is followed by a digit, ignore \N and the digit.
If \N is followed by a non-digit, the next non-digit
ends the character number; the two delimiters need not match.
Kristaps calls that "gross, but not our fault".

For now, i'm fixing \N only.  Other escapes taking numeric arguments
may or may not need similar handling, but \N is by far the most
important for practical purposes.

ok kristaps@

Implement the missing text production macros (Bsx Bx Dx Fx Nx Ox Ux Bt Ud).
Some macros work without explicit implementation (At Db Os St).
ok kristaps@

Fix mandoc_escape() function argument names.  From a fix by Abhinav
Upadhyay, thanks!

Sync to groff, and add tier I and II NetBSD architectures.
ok kristaps@

Remove a bunch of useless assignments,
and assert that print_bvspace cannot be called on NULL pointers.
No change in behaviour, none of these were bugs,
but the code becomes easier to understand.
Based on a clang report posted by joerg@; ok kristaps@.

Always print <table> column widths in -T[x]html;
if desired, they can be overridden in the CSS file.
Suggested by kristaps@, and i always like to simplify code.

A bit more precision and nicer wording in the descriptions
of -Ofragment and -Tman; using input from jmc@ and kristaps@.

Make apropos results-gathering able to error out and clean up before
making the utility exit non-zero.

Remove some unnecessary variables and note that mchars_alloc never returns
NULL.

Use a binary tree (for now, unbalanced) for deduping the records in the
results array.  This is much faster than the previous method, a linear
search, at a small cost.  Note that array offsets are used instead of
storing the res pointer because we may realloc the results vector.

The documented flags in mandocdb (-u, -d) were switched.  Fix this.

Critical fix in the new -Tman lookaside buffer code. Gah..

Note volatility of apropos and cut out old news update.

Tweak Makefile and add config.h to -Tman to allow cross-compiling on
Windows (via MingW).

Use `Mt' instead of `Aq' for email address.

Get ready for version.  I'm bumping the minor release to 1.12 because
this involves both a major functionality addition (-Tman), a new utility
(apropos), and both apropos and mandocdb being built by default.

Use mandoc_realloc() in apropos, as we're linking to libmandoc.a.

Implement a basic -Tman `Rv', like `Ex'.

Tidy up -Tman output.  This has NO functional change: (1) introduced a
state struct instead of using global statics; (2) documented throughout
the file; (3) fixed a situation of reaching past the end of our buffer
for zero-length strings; (4) alpha-ordered the functions.  (1) and (3)
ok schwarze@.  (2) and (4) are purely style and documentation.

Lift hard-coded limit of results.

Clean up file a bit: remove errx and err function pointers from the
state struct (directly using fprintf and perror to do this); add some
in-line documentation; remove state init and destroy directly to the
main function.

Make apropos and mandocdb build by default.

Add more version notes to www.

Nix end-of-line whitespace.

Import apropos from mandoc-tools after inlining all source files
(originally including extern.h, state.c, and sort.c).  The apropos
utility interfaces with the databases of mandocdb to provide semantic
searching capabilities.  It Works For Me, but will need lots of cleanup
in the coming months.

If -Tman is specified and input is -man, echo the preprocessed (`so'
replaced by file) input.  This replaces earlier behaviour of doing
nothing, which I found unexpected (mandoc should always output).

This requires a buffer in read.c that saves the input lines before being
parsed, with a special hook if `so' is invoked.  This buffer is just
flushed to output if -mman is the input.

While mucking around doing this, I also alpha-ordered the mandoc.h
functions.

Ok schwarze@, with no screaming when the polished patch was published.

Add -Ofragment mode to release notes.

Add the -Ofragment option to -T[]x]html.  This accomodates for embedding
manual output in existing HTML or XHTML documents, e.g., when invoking
mandoc from an SSI or CGI.

Break schwarze@'s release notes into sections.  Ok schwarze@.

Make -T[x]html suppress output with \& (and similar zwsp points).  This
fixes lynx's rendering of manuals with the \&, which were rendering as
&#8203; in the text.  Reported by Paul de Weerd, thanks!

implement .Ap .Bd .Bo .Bq .D1 .Ic .Lp .Oo .Pf .Po .Ss .Sx .Sy .br .sp
implement .Bl -bullet
add more information to the .TH line
escape dots at the beginnings of lines
add trailing newline character at the end of the file
do not misinterpret the ROOT block as .Ap

list the work done during s2k11

even though .Bl is not callable, groff complains when it appears
unescaped on a macro line, so lets just escape it;
noticed by jmc@

Reorganize part of the content:

1) Move the LANGUAGE SYNTAX from mdoc(7) and man(7) to roff(7),
it's common to both and it's actually roff syntax.
2) Move the MACRO SYNTAX down to the bottom, such that the less
technical parts MANUAL STRUCTURE and MACRO OVERVIEW get to the top.

Getting everything to again fit together after the reshuffling
required various adjustments; also adjust and improve
the DESCRIPTIONS while there.

feedback and "go ahead"  jmc@ kristaps@

restore alphabetical order for the -Toutput list, and use a width
specifier that makes it look nicer;
from jmc@, ok kristaps@

typos found by jmc@

As noticed by kristaps@, when breaking an overflowing line,
forget about pending whitespace (vbl), or the next line would
be misaligned and potentially too long; but i'm fixing this
in a simpler way than he proposed.
Also remove the kludges in .HP that compensated for this bug.

sync to groff: support .Lb -libdwarf, update .Lb -libelf
after Werner Lemberg committed a patch by Joseph Koshy

Major rewrite of the horizontal spacing of tables
to work both with and without frames and rulers.
ok kristaps@

add a MACRO OVERVIEW section, similar to the one in mdoc(7);
writing this for man(7), too, was suggested by kristaps@

Using user-defined macros, surprisingly, it is possible
to have *next*-line head arguments on the *same* input line.
So .TP must not assume that a head argument with a matching
input line number is a same-line argument (and access a NULL pointer).
Bug found and fix tested by kristaps@ with groff_hdtbl(7).

do not assign pointers to literal strings
to variables that might be changed;
from kristaps@

When advancing the left margin, .RS also needs to reset the right margin
to the default and check that the left does not outgrow the right one.
Otherwise, the (rmargin >= offset) assertion fails in term_flushln().
Bug found and fix tested by kristaps@ with NetBSD slapo-retcode(5).

Sync print_mdoc_head to print_man_head;
this was forgotten after man_term.c rev. 1.25 on March 2, 2010.
The benefit is a sane page header line when .Dt is very long.
Reminded by Thomas Klausner <wiz at NetBSD>, thanks.

Remove the terminal frontend flag TERMP_NOLPAD.

In columnated contexts (.Bl -column, .Bl -tag, .IP, .TP, .HP etc.), do not
pad after writing a column.  Instead, always pad before writing content.

In itself, this change avoids:
 - writing trailing whitespace in some situations
 - with .fi/.nf in .HP, breaking lines that were already padded

It allows several bugfixes included in this patch:
 - Do not count backspace as a character with positive width.
 - Set up proper indentation when encountering .fi/.nf in .HP.
 - Adjust the .HP indentation width to what groff does.
 - Never unlimit the right margin unless in the final column.

ok kristaps@

Breaking the line at a hyphen is only allowed if the hyphen
is both preceded and followed by an alphabetic character.
ok kristaps@

Fix another regression introduced in 1.11.7:
If a string is defined in terms of itself, the REPARSE_LIMIT in read.c
used to break the cycle.  This no longer works since all the work
is now done in the function roff_res(), looping indefinitely.

Make this loop finite by arbitrarily limiting the number of times one
string may be expanded; when that limit is reached, leave the remaining
string references unexpanded.

This changes behaviour compared to 1.11.5, where the whole line would
have been dropped.  The new behaviour is better because it loses less
information.  We don't want to imitate groff-1.20.1 behaviour anyway
because groff aborts parsing of the whole file.

ok kristaps@

fix a regression introduced in 1.11.7:
even a breakable hyphen may be bold or underlined
ok kristaps@

Support nesting of indented blocks.

This patch was originally written in July 2011 by kristaps@,
i promptly committed it to OpenBSD, and then it was forgotten.
Now i rediscovered it when merging 1.11.7 to OpenBSD.

ok kristaps@  (on his own patch :)

two issues were reported again

forgotten Copyright bumps; no code change
found while syncing to OpenBSD

Add a MACRO OVERVIEW, listing all macros ordered by purpose,
each with a one-line discription.  Use this when wondering
which macro fits best for your particular use case, and whether
there are alternatives.
feedback ond ok jmc@, ok kristaps@

Initial, incomplete support for -Tman
to convert mdoc(7) documents to the man(7) language.
This is work in progress and will be developed in tree.
It does already handle the cat(1) manual,
but will hardly handle all your fancy manuals yet.
go ahead  kristaps@ jmc@ millert@ deraadt@

fix an obvious typo: sz was used uninitialized
found while merging to OpenBSD

support ".St -iso8601"; committing on behalf of jmc@

It's unknown whether `SH' and `SS' closing out `nf' literalism is
portable, so document it in COMPATIBILITY.

Revert removal of tab warning, suggested by schwarze@.

Remove check for tab.  man(7) says tab is Ok.