document .as and .ce

Parse and ignore the roff(7) .ce request (center some lines).

We even parse and ignore the .ad request (adjustment mode),
and it doesn't make sense to more prominently warn about
temporary than about permanent adjustment changes.

Request found by naddy@ in xloadimage(1) and by juanfra@ in racket(1).

Implement the roff(7) .as request (append to user-defined string).
Missing feature found by jca@ in ratpoison(1).
The ratpoison(1) manual still doesn't work because it uses .shift
and .while, too (apparently, ratpoison is so complex that it
needs a Turing-complete language to even format its manual :-).

Written at Christchurch International Airport.

Handle some predefined read-only number registers, e.g. .H and .V.
In particular, this improves handling of the pod2man(1) preamble;
for examples of the effect, see some author names in perlthrtut(1).

Missing feature reported by Andreas Voegele <mail at andreasvoegele dot com>
more than two years ago.  Written at Christchurch International Airport.

use .At where appropriate; from Jan Stary <hans at stare dot cz>

Supplement the documentation of the .St macro by minimal commentary
regarding the content and relationships of the various standards,
and sort and group them.
tweaks and ok guenther@, ok millert@ sobrado@ jmc@

Implement the \: (optional line break) escape sequence,
documented in the Ossanna-Kernighan-Ritter troff manual
and also supported by groff.

Missing feature reported by Steffen Nurpmeso <sdaoden at gmail dot com>.

Treat the line after .Cd as a single argument.
This doesn't hurt normal manual display
and makes the mandocdb(8) database more useful.

Keep words after .Ic together in a single argument.
This doesn't hurt normal manual display
and makes the mandocdb(8) database more useful.

Change markup of some fixed strings from .Ar to .Cm.

Always compare arch case-insensitively.

Avoid the risk of trying to modify a literal string.

Always store the arch in lower-case only.
Reduces database size by ~0.5%, and by ~1.5% with -Q.

Get rid of the local keys table, use the new mansearch_const.c.
No functional change.

Support a second -v on mandocdb(8) to show keys while they are being added;
i need that for debugging, in particular to be used with -t.
To be able to do so, provide a global table of key names, for reuse.

Cope with slightly broken NAME sections in man(7) pages
having a trailing comma after the last name, like this:

ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions

Sort the macro keys by their real-world frequency to reduce the average
mask size.  No functional change.

This shrinks the standard /usr/share/man database by 7%, now at 10.3x
the size of whatis.db, and with -Q even by 11%, now at 3.0x of whatis.db.
Now i'm out of ideas to easily shrink the size of the database.

Drop the AUTOINCREMENT PRIMARY KEYs from the mlinks and keys tables.
They are completely unused, and i cannot imagine what they *could*
ever be used for; but apparently, they are expensive to generate.

Standard DB build time goes down by 10%, now at 1.9x of makewhatis.
Standard DB size goes down by 4%, now at 11x of makewhatis.
DB build time with -Q goes down by 15%, now at 0.28x of makewhatis.
DB size with -Q goes down by 3%, now at 3.35x of makewhatis.

Despite some experimenting, i'm unable to find any relevant effect of
creating an index for the keys table on apropos(1) search times;
apparently, adding that index was premature optimization in the first
place; so, stop adding that index.

Its root gone, the following evil is reduced (/usr/share/man on my notebook)
 - DB build time with -Q goes down by 15%, now at 1/3 of makewhatis
 - DB size with -Q goes down by 35%, now at 3.5x of makewhatis
 - full DB build time goes down by 12%, now at 2.1x of makewhatis
 - full DB size goes down by 42%, now at 11.5x of makewhatis

Remove useless use of strnlen(3).
Yuckiness pointed out by deraadt@.

Cache the result of uname(3) such that we don't need to call it
over and over again for each manual; found with gprof(1).
Speeds up mandocdb(8) -Q by 3%, now at 39.5% of makewhatis(8).

Gprof(1) is fun.  You should use it more often.

Another 10% speedup for mandocdb(8) -Q, and even 3% without -Q.
With -Q, we are now at 41% of the time required by makewhatis(8).

Do not copy predefined strings into the dynamic string table, just
leave them in their own static table and use that one as a fallback
at lookup time.  This saves us copying and deleting them for each manual.
No functional change.

Another 18% speedup for mandocdb(8) -Q, found by gprof(1).
In -Q mode, refrain form validating and normalizing the format
of the date given in .Dd or .TH, as it won't be used anyway.

For /usr/share/man, mandocdb -Q now takes 45% of the time of makewhatis(8).

Another 25% speedup for mandocdb(8) -Q mode, found with gprof(1).
For /usr/share/man, we only need 56% of the time of makewhatis(8) now.

In groff, user-defined macros clashing with mdoc(7) or man(7)
standard macros are cleared when parsing the .Dd or .TH macro,
respectively.  Of course, we continue doing that in standard mode
to assure full groff bug compatibility.

However, in -Q mode, full groff bug compatibility makes no sense
when it's unreasonably expensive, so skip this step in -Q mode.
Real-world manuals hardly ever redefine standard macros,
that's terrible style, and if they do, it's pointless to do so
before .Dd or .TH because it has no effect.  Even if someone does,
it's extremely unlikely to break mandocdb(8) -Q parsing because we
abort the parse sequence after the NAME section, anyway.

So if you manually redefine .Sh, .Nm, .Nd, or .SH in a way that doesn't
work at all and rely on .Dd or .TH to fix it up for you, your broken
manual will no longer get a perfect apropos(1) entry until you re-run
mandocdb(8) without -Q.  It think that consequence is acceptable
in order to get a 25% speedup for everyone else.

Do not sync to disk after each individual manual page (duh!),
only sync to disk one single time when all data is ready.

Rebuild times for /usr/share/man/mandoc.db shrink on my notebook:
In standard mode from 45 seconds to 11 seconds   (75% reduction)
In -Q mode       from 25 seconds to 3.1 seconds  (87% reduction)
For comparison: makewhatis(8):      4.2 seconds

That is, in -Q mode, we are now *faster* than the existing makewhatis(8),
and careful profiling shows there is still a lot of room for improval.

Fix mandocdb(8) -d and -u.
It was broken by recent optimizations.

Rename dbindex() to dbadd() to be less confusing.
The concept of an index file is gone since the switch to SQLite.
No functional change.

Remove the redundant "file" column from the "mlinks" table.
The contents can easily be reconstructed from sec, arch, name, form.
Shrinks the database by another 3% in standard mode and 9% in -Q mode.

Drop Nd from the mpages table, it is still in the keys table.
This shrinks the database in standard mode by 3%, in -Q mode by 9%,
without loss of functionality.

Joerg Sonnenberger contributed copyrightable amounts of text to
some files.  To make it clear that he also put his contributions
under the ISC license, with his explicit permission, add his
Copyright notice to the relevant files.  No code change.

Cope with mparse_alloc() interface change.

Add an option -Q (quick) to mandocdb(8)
for accelerated generation of reduced-size databases.

Implement this by allowing the parsers to optionally
abort the parse sequence after the NAME section.

While here, garbage collect the unused void *arg attribute of
struct mparse and mparse_alloc() and fix some errors in mandoc(3).

This reduces the processing time of mandocdb(8) on /usr/share/man
by a factor of 2 and the database size by a factor of 4.
However, it still takes 5 times the time and 6 times the space
of makewhatis(8), so more work is clearly needed.

Tag functions with format strings as arguments as printf-like.
Fix one case where a non-literal is used as format string.
Fix another case where a variable is formatted using the wrong type.

Merge NetBSD's r1.4: Rename data to getdata to work around bugs in the
PPC64 toolchain.

Rip out the complete "reachable" checks, without replacement.
It's a pity i spent time during t2k13 writing this; however,
when an entire concept is busted, let us not look back,

There is no such thing as an unreachable page.  Even if you are crazy
enough to put a page starting with ".Dt NAMEI 9" into a file man1/cat.1,
we now make sure that it can be found by all of the following:
Nm=namei Nm=cat sec=1 sec=9
It will always be displayed as:
cat(1) - pathname lookup
So you know that you have to type `man cat` to get at it.
That obsoletes the concept of "unreachable manuals" for good.

Remove the obsolete file name column from the mpages table.
This column wasn't helpful because one manpage can have multiple MLINKS.
Use the file name column in the mlinks table, instead.

Remove the obsolete sec and arch columns from the mpages table.
They were confusing because a manpage can have MLINKS in different
sections and architectures.

Reimplement apropos -s NUM -S ARCH EXPR by internally converting it to
apropos \( EXPR \) -a 'sec~^NUM$' -a 'arch~^(ARCH|any)$'
in preparation for removal of sec and arch from the mpage table.

Almost no functional change except for the following bonus:
This also makes sure that for cross-section and cross-arch MLINKs,
all of the following work:
apropos -s 1 encrypt
apropos -s 8 encrypt
apropos -s 1 makekey
apropos -s 8 makekey

While here, print error messages about invalid regexps to stderr.

Put section and architecture info into the keys table,
in preparation for removing them from the mpages table,
aiming for cleaner and more uniform interfaces.
Database growth is below 4%, part of which will be reclaimed.

As a bonus, this allows searches like:
./obj/apropos An=kettenis -a arch=ppc
./obj/apropos An=kettenis -a sec~[^4]

New implementation of complex search criteria using \(, \), -a because
the old implementation got lost in the Berkeley to SQLite switch.
Note that this is not just feature creep, but required for upcoming
database format cleanup and simplification.

Put mansearch.{h,c}, manpage.c, and compat_ohash.{h,c}
into the distribution tarball.  Bump VERSION.

Put ./configure into the distributin tarball.

Use C99 uint32_t, not BSD-style u_int32_t.
Needed for Solaris 10 as reported by Matthias Scheler.

Even though strnlen(3) is required by POSIX 2008,
Matthias Scheler reports than Solaris 10 lacks it.
While here, sort the declarations in config.h
and move the headers to the top.

Clean up feature tests:
* Split the configure steering script out of the Makefile.
* Let the configure step depend on the test sources.
* Clean up the test programs such that they can be run.

Avoid "utf8" in the names of a function and a struct member
that don't necessarily have anything to do with UTF-8.
Just renaming, no functional change.

Do not put UTF-8-encoded strings into the database by default, use ASCII.
Just like for mandoc(1), provide a -Tutf8 option for people who want that.

Polish the mlink_add() interface:
Allocate memory inside, not in the callers.
No functional change.

Check all MLINKS for consistency with the content of the manual page,
not just the first one.  This doesn't change how the check is done,
but just which MLINKS are checked.

Since the functions in read.c are part of the mandoc(3) library,
do not print to stderr.  Instead, properly use the mmsg callback.
Issue noticed by Abhinav Upadhyay <er dot abhinav dot upadhyay
at gmail dot com> and Thomas Klausner <wiz at NetBSD>.

Support .St -p1003.1-2013, "IEEE Std 1003.1-2008/Cor 1-2013".

Note that the POSIX-2008 standard remains in force, so please refrain
from wholesale 2008 -> 2013 replacements.  Make sure to only use the
new -p1003.1-2013 argument for cases where "IEEE Std 1003.1(TM)-2008/
Cor 1-2013, IEEE Standard for Information Technology--Portable
Operating System Interface (POSIX(R)), Technical Corrigendum 1"
actually changes something in the standard with respect to the
specific function documented in the manual you touch.  Otherwise,
please continue using .St -p1003.1-2008.

Triggered by a similar, but slightly incorrect patch from jmc@;
ok guenther@.

Simplify: Remove an unused argument from the mandoc_eos() function.
No functional change.

Provide strcasestr(3) and strsep(3) for Solaris 10 compat;
reported missing by Matthias Scheler <tron at NetBSD> via wiz@.

Do not trigger end-of-sentence spacing by trailing punctuation
at the end of partial implicit macros.  Prodded by jmc@.

Actually, this is a revert of rev. 1.64 Fri May 14 14:09:13 2010 UTC
by kristaps@, with this original commit message:
"Block-implicit macros now up-propogate end-of-sentence spacing.
NOTE: GROFF IS NOT SMART ENOUGH TO DO THIS."
Please speak after me: Then why the hell should we?

We already weakened this in rev. 1.93 Sun Jul 18 17:00:26 2010 UTC,
but that weakening was insufficient.  Let's take it out completely.

Admittedly, there are two places in OpenBSD base where what Kristaps
did make the output nicer, in calloc(3) and in fish(6).  But both are
atypical.  There are 18 other places where this revert makes the
output nicer, the typical case being:
"Mail status is shown as ``No Mail.''  if there is no mail."
You do *not* want the EOS spacing after ``No Mail.'' in that sentence.

Yet another regression introduced by Kristaps when he switched from
Berkeley DB to SQLite3: In the .In parser, the logic got inverted.
The resulting NULL pointer access was found by clang;
scan log provided by Ulrich Spoerlein <uqs at FreeBSD>.

The best fix is to simply remove the whole, pointless custom
handler function for .In and let the framework do its work.
Now searching for included header files actually works.

While here, remove the similarly pointless custom .St handler,
fix the return value of the .Fd handler and disentangle the
spaghetti in the .Nm handler.

remove assignments that will be overwritten right afterwards,
and remove pointless local variables;
found in a clang output from Ulrich Spoerlein <uqs at FreeBSD>

update the link to the ISC license
and note that the pkgsrc port was updated to 1.12.3

Add missing description of .UR/.UE.
While here, also add .EX/.EE and .PD to the MACRO SYNTAX table.

release 1.12.3

Experimental feature to let apropos(1) show different keys than .Nd.
This really takes us beyond what grep -R /usr/*/man/ can do
because now you can search for pages by *one* criterion and then
display the contents of *another* macro from those pages, like in
$ apropos -O Ox Fa~wchar
to get an impression how long wide character handling is available.

Split buildnames() out of mansearch(); the latter function is getting
too long and unwieldy, but will grow more code soon.  No functional change.

Oops, missed one:
Remove duplicate const specifier from a call to mandoc_escape().
Found by Thomas Klausner <wiz at NetBSD dot org> using clang.
No functional change.

Remove duplicate const specifiers from the declaration of mandoc_escape().
Found by Thomas Klausner <wiz at NetBSD dot org> using clang.
No functional change.

Oops, that segfaulted after deleting an mlink from the list.
Fix the loop logic in mlinks_undupe().

Split mlinks_undupe() out of mpages_merge()
such that the check for source manuals of the same name
can be done for multiple mlinks pointing to the same preformatted mpage.

Change the mansearch() interface to use the mlinks table in the database
and return a list of names with sections, used by apropos(1) for display.
While here, improve uniformity of the interface by allocating the file
name dynamically, just like the names list and the description.

Save the MLINK name into the database, too;
apropos(1) will need it to display its results.

Write more than one mlink per mpage to the database.
Not yet used by apropos(1).

Allow saving more than one mlink per mpage in the mlinks ohash.
We are still only using one of them for now.
Actually, we are now using a different one,
but the order the mlinks are found is random anyway.

Enable the framework code to allow more than one mlink per mpage.
Not used yet.

Clean up the interface of mlink_add().
Consistently use "fsec" and "fform" for info derived from the file name.
No functional change.

Another step on the way to clear naming, this time regarding mlinks:
* rename global ohash filenames to mlinks
* rename ofadd() to mlink_add()
* fold fileadd() and inoadd() into mlink_add()
* fold filecheck() into mpages_merge()
Still no functional change.

Split struct mlink out of struct mpage.
Still a 1:1 relation, no functional change yet.

Add an additional mlinks table to the database, redundant for now,
both because it contains nothing but a subset of the data of the
existing mpages table and because the relationship of mpage and mlink
entries is still 1:1.  But all that will eventually change.

Drop the mpages_list, use the existing mpages ohash for iteration.
No functional change except that the order of database entries changes,
which doesn't matter anyway.

The name "id" is terrible for a struct.
Make this more searchable by calling it "inodev".
No functional change.

To better support MLINKS, we will have to split the "docs" database
table into two tables, on for actual files on disk, one for (often
multiple) directory entries pointing to them.  That implies splitting
struct of into two structs, to be called "mpage" and "mlink",
respectively.  As a preparation, globally rename "of" and "inos"
to "mpage".  No functional change.

Stop parsing man(7) input when we found all we were searching for,
such that we don't trigger an assertion on a duplicate NAME section.

Rework the documentation of Spaces, using the Ossanna/Kernighan/Ritter
Heirloom Nroff/Troff User's Manual at the authoritative reference.
Part of our text was outright wrong.

Also, refrain from advertising the paddable non-breaking space `\~'
in the DESCRIPTION, for three reasons:  For nroff mode, -Tascii, and
fixed width fonts in general, it makes no difference, so keep the
discussion simple.  Compared to `\ ', '\~' is of questionable portability.
And if you want to keep words together, it is also more usual that you
don't want padding to intervene either.

Finally, drop the `\c' escape sequence (interrupt text processing)
which is not a special character but an input processing instruction
akin to the \<newline> escape sequence.

merge from VERSION_1_12

I have no idea how it happened that \B, \H, \h, \L, and \l got
mapped to ESCAPE_NUMBERED (which is for \N and only for \N), that
made no sense at all.  Properly remap them to ESCAPE_IGNORE.

While here, move \B and \w from the group taking number arguments
to the group taking string arguments; right now, that doesn't imply
any functional change, but if we ever go ahead and implement a
parser for roff(7) numerical expressions, it will suddenly start
to matter, and cause confusion.

The roff language really has two groups of basic building blocks:
Requests and escape sequences.  Consequently, supplement the
REQUEST REFERENCE by an ESCAPE SEQUENCE REFERENCE, such that people
no longer need to guess or experiment what mandoc(1) implements,
what it parses and ignores, and what it doesn't handle at all.

Parse and ignore the roff(7) escape sequences \d (move half line down)
und \u (move half line up).  Found by bentley@ in some DocBook crap.

Implement .Fo/.Fa/.Fc indentation and break handling for -Tman.

Oops, .Fa never breaks the output line in the middle of any of its
arguments, not even outside SYNOPSIS mode.  Quite surprising as .Fn
does break the line in the middle of its arguments outside SYNOPSIS
mode, and only doesn't do that in SYNOPSIS mode.  Wonders of groff...

Garbage collect two local variables each used only one single time.

In the SYNOPSIS, implement hanging indentation for .Fo
and avoid output line breaks inside .Fa arguments.
This reduces groff-mandoc differences in OpenBSD base by more than 8%.
Patch from Franco Fichtner <franco at lastsummer dot de> (DragonFly).

Support .St -xsh4.2, the System Interfaces part of the original Single
UNIX Specification.  As this one appears to be used in the wild and we
already have -xpg4.2 and even -xsh5, it makes sense to add this one.
Note that calling the original SUS XPG4.2 appears to be more common
than calling it SUSv1, so it's ok that we don't have .St -susv1.
From Sascha Wildner <saw at online dot de> (DragonFly) via Franco Fichtner.

s/[Nn]ull/NUL/ in comments where appropriate;
suggested by Thomas Klausner <wiz @ NetBSD dot org>.

Do not break output lines in .Fn function arguments in SYNOPSIS mode.
Following an idea from Franco Fichtner, but implemented more cleanly.
This reduces groff-mandoc-differences in OpenBSD base by a fantastic 7.5%.

Delete the unused flag TERMP_IGNDELIM
and the empty callback termp_igndelim_pre().
Sort the remaining termp flags.

Implement SYNOPSIS .Fn indentation for -Tman.

It turns out SYNOPSIS mode does not imply .Bk in general,
but only within .Nm blocks.  Simplify the code accordingly.

Triggered by research done by Franco Fichtner.

When deciding whether two consecutive macros are on the same input line,
we have to compare the line where the first one *ends* (not where it begins)
to the line where the second one starts.
This fixes the bug that .Bk allowed output line breaks right after block
macros spanning more than one input line, even when the next macro follows
on the same line.

Implement a long-standing desideratum,
hanging indentation for .Fn in SYNOPSIS mode,
exploiting the new trailspace feature
by deliberately *NOT* using it.

Polishing the worms in my favourite can, term_flushln().

The TERMP_TWOSPACE flag i introduced in August 2009 was idiosyncratic
and served only a very narrow purpose.  Replace it by a more intuitive
and more general termp attribute "trailspace", to be used together
with TERMP_NOBREAK, to request a minimum amount of whitespace at
the end of the current column.  Adapt all code to the new interface.

No functional change intended;
code reviews to confirm that are welcome *eg*.

Fix end-of-sentence spacing after the DragonFly text production macro.
Patch from Franco Fichtner <franco at lastsummer dot de>.

Implement end-of-sentence spacing at the end of man(7) macro lines.

Patch from Franco Fichtner <franco at lastsummer dot de> (DragonFly).

Document the alternative syntax \C'uXXXX' for Unicode characters.
Forgotten when committing mandoc.c rev. 1.70.

In quoted macro arguments, double quotes can be quoted by doubling them.
For a long time, we handle this in roff(7) and man(7) macros.
Now add correct handling for the mdoc(7) case, too.

Closely based on a patch by Tsugutomo dot ENAMI at jp dot sony dot com,
see http://gnats.netbsd.org/cgi-bin/query-pr-single.pl?number=48438
received via Thomas Klausner (wiz@), slightly tweaked by me.