9508192e44
--- MAJOR NEW FEATURES ---
* apropos(1): Reimplement complete semantic search functionality
without the dependency on SQLite3, using only POSIX APIs.
This comes with a completely new mandoc.db(5) file format.
* man(1): Support more than one tag entry for the same search term,
plus some minor improvements to the less(1) :t support.
* -Thtml: Use real macro names for CSS classes.
Systematic cleanup of and many improvements to mandoc.css.
* -Thtml: Produce human readable HTML code by using indentation
and better line breaks. Improve various HTML elements,
and trim several useless ones.
* New catman(8) utility, still somewhat experimental.
* Now includes a portable version of the OpenBSD mandoc regression
suite, see regress/regress.pl.1 for details.
--- REMOVED FUNCTIONALITY ---
* Operating systems that don't provide mmap(3) are no longer supported.
* Drop support for manpath(1). Even if your system has manpath(1),
it is simpler to use MANPATH_DEFAULT in configure.local for
operating system defaults, man.conf(5) for machine-specific
modifications, and ${MANPATH}, -m, and -M for user preferences
than to bother with the complexity of manpath(1).
* makewhatis(8) -p: No longer warn about missing MLINKS since these
are no longer needed for anything.
--- MINOR NEW FEATURES ---
* mdoc(7): Warn about invalid punctuation and content below NAME.
* mdoc(7): Warn about .Xr lacking the second argument (section).
* mdoc(7): Warn about violations of the rule "new sentence, new line".
* roff(7): Warn about trailing whitespace at the end of comments.
* mdoc(7): Improve rendering of double quotes.
* mdoc(7): Always do text production in the validator, never in the
formatters. Cleaner, simpler, shorter, helps NetBSD apropos(1)
and also makes -Ttree output more useful.
* -Ttree: Show metadata and some additional node flags.
New -Onoval output option to show the unvalidated tree.
--- RELIABILITY BUGFIXES ---
* man(1): Make "man -l" work with standard input from a pipe or file,
as long as standard output is a terminal.
* man(7): Fix out of bounds read access if a text node immediately
preceded the first .SH header.
* mdoc(7): Fix out of bounds read access for .Bl without a type
but with a width.
* mdoc(7): Fix out of bounds read access for .Bl -column starting
with a tab character instead of a child .It macro.
* mdoc(7): Fix syntax tree corruption leading to segfaults caused
by stray block end macros in nested blocks of mismatching type.
* man(1): Fix NULL dereference when the first of multiple pages
shown was preformatted.
* mdoc(7): Fix syntax tree corruption leading to NULL dereference
caused by partial implicit macros inside .Bl -column table cells.
* mdoc(7): Fix syntax tree corruption leading to NULL dereference
for macro sequences like .Bl .Bl .It Bo .El .It.
* mdoc(7): Fix syntax tree corruption leading to NULL dereference
caused by .Ta following a nested .Bl -column breaking another block.
* mdoc(7): Fix syntax tree corruption sometimes leading to NULL
dereference caused by indirectly broken .Nd or .Nm blocks.
* mdoc(7) -Thtml: Fix a NULL dereference for .Bl -column with 0 columns.
* mdoc(7): Fix NULL dereference in some specific cases of a
block-end macro calling another block-end macro.
* mdoc(7): Fix NULL dereference if the only child of the head
of the first .Sh was an empty in-line macro.
* eqn(7): Fix NULL dereference in the terminal formatter
for empty matrices and empty square roots.
* mdoc(7): Fix an assertion failure for a .Bd without a type that
breaks another block.
* mdoc(7): Fix an assertion failure that happened for some .Bl -column
lists containing a column width of "-4n", "-3n", or "-2n".
* mdoc(7): Fix an assertion failure caused by .Bl -column without .It
but containing eqn(7) or tbl(7) code.
* roff(7): Fix an assertion failure caused by \z\[u00FF] with -Tps/-Tpdf.
* roff(7): Fix an assertion failures caused by whitespace inside \o''
(overstrike) sequences.
* -Thtml: Fix an assertion failure caused by -Oman or -Oincludes of
excessive length.
--- PORTABILITY IMPROVEMENTS ---
* man(1): Do not mix stdio narrow and wide stream orientation
on stdout, which could cause output corruption on glibc.
* mandoc(1): Autodetect a suitable locale for -Tutf8 mode.
* ./configure: Autodetect whether PATH_MAX and O_DIRECTORY are defined.
* ./configure: Autodetect if nanosleep(3) needs -lrt.
* ./configure: Provide an ${LN} configuration variable.
* ./configure: Put compiler arguments that may contain -l at the end.
--- MINOR BUGFIXES ---
* mdoc(7): Fix SYNOPSIS output if the first child of .Nm is a macro.
* mdoc(7) -Thtml: Improve formatting of .Bl -tag with short tags.
* man(7) -Thtml: Preserve whitespace in .nf (nofill) mode.
* mandoc(1): Error out on invalid output options on the command line.
--- STRUCTURAL CHANGES, no functional change ---
* Redesign part of the mandoc_html(3) interfaces, making them much
easier to use and reducing the amount of code by a few hundred lines.
--- THANKS TO ---
* Michael Stapelberg (Debian) for designing the new mandocd(8)
and parts of the new catman(8), for release testing, and for a
number of patches and bug reports.
* Baptiste Daroussin (FreeBSD) for profiling the new makewhatis(8)
implementation and suggesting an algorithmic improvement which
more than doubled performance, and for a few bug reports.
* Ed Maste (FreeBSD) for an important patch improving reproducibility
of builds in makewhatis(8), and for a few bug reports.
* Theo Buehler (OpenBSD) for almost twenty important bug reports,
most of them found by systematic afl(1) fuzzing.
* Benny Lofgren, David Dahlberg, and in particular Vadim Zhukov
for crucial help in getting .Bl -tag CSS formatting fixed.
* Svyatoslav Mishyn (Crux Linux) for an initial version of the
patch to autodetect a suitable locale for -Tutf8 mode
and for release testing.
* Jason McIntyre (OpenBSD) for multiple useful discussions
and a number of bug reports.
* Sevan Janiyan (NetBSD) for extensive release testing and multiple
bug reports.
* Thomas Klausner and Christos Zoulas (NetBSD), Yuri Pankov (illumos),
and Leah Neukirchen (Void Linux) for release testing and bug reports.
* Ulrich Spoerlein (FreeBSD) for release testing.
* Alexander Bluhm, Andrew Fresh, Antoine Jacoutot, Antony Bentley,
Christian Weisgerber, Jonathan Gray, Marc Espie, Martijn van Duren,
Stuart Henderson, Ted Unangst, Theo de Raadt (OpenBSD), Abhinav
Upadhyay, Kamil Rytarowski (NetBSD), Aaron M. Ucko, Bdale Garbee,
Reiner Herrmann, Shane Kerr (Debian), Daniel Sabogal (Alpine Linux),
Carsten Kunze (Heirloom roff), Kristaps Dzonsons (bsd.lv),
Anton Lindqvist, Jan Stary, Jeremy A. Mates, Mark Patruck,
Pavan Maddamsetti, Sean Levy <attila@stalphonsos.com>, and
Tiago Silva for bug reports.
* Brent Cook, Marc Espie, Philip Guenther, Todd Miller (OpenBSD)
and Markus Waldeck for useful discussions.
* And as usual, OpenCSW for providing me with a Solaris 9/10/11
testing environment.
229 lines
5.7 KiB
Groff
229 lines
5.7 KiB
Groff
.\" Id: mandoc.db.5,v 1.5 2016/08/01 12:27:15 schwarze Exp
|
|
.\"
|
|
.\" Copyright (c) 2014, 2016 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd August 1, 2016
|
|
.Dt MANDOC.DB 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mandoc.db
|
|
.Nd manual page database
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
file format is used to store information about installed manual
|
|
pages to facilitate semantic searching for manuals.
|
|
Each manual page tree contains its own
|
|
.Nm
|
|
file; see
|
|
.Sx FILES
|
|
for examples.
|
|
.Pp
|
|
Such database files are generated by
|
|
.Xr makewhatis 8
|
|
and used by
|
|
.Xr man 1 ,
|
|
.Xr apropos 1
|
|
and
|
|
.Xr whatis 1 .
|
|
.Pp
|
|
The file format uses three datatypes:
|
|
.Pp
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
32-bit signed integer numbers in big endian (network) byte ordering
|
|
.It
|
|
NUL-terminated strings
|
|
.It
|
|
lists of NUL-terminated strings, terminated by a second NUL character
|
|
.El
|
|
.Pp
|
|
Numbers are aligned to four-byte boundaries; where they follow
|
|
strings or lists of strings, padding with additional NUL characters
|
|
occurs.
|
|
Some, but not all, numbers point to positions in the file.
|
|
These pointers are measured in bytes, and the first byte of the
|
|
file is considered to be byte 0.
|
|
.Pp
|
|
Each file consists of:
|
|
.Pp
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
One magic number, 0x3a7d0cdb.
|
|
.It
|
|
One version number, currently 1.
|
|
.It
|
|
One pointer to the macros table.
|
|
.It
|
|
One pointer to the final magic number.
|
|
.It
|
|
The pages table (variable length).
|
|
.It
|
|
The macros table (variable length).
|
|
.It
|
|
The magic number once again, 0x3a7d0cdb.
|
|
.El
|
|
.Pp
|
|
The pages table contains one entry for each physical manual page
|
|
file, no matter how many hard and soft links it may have in the
|
|
file system.
|
|
The pages table consists of:
|
|
.Pp
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
The number of pages in the database.
|
|
.It
|
|
For each page:
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
One pointer to the list of names.
|
|
.It
|
|
One pointer to the list of sections.
|
|
.It
|
|
One pointer to the list of architectures
|
|
or 0 if the page is machine-independent.
|
|
.It
|
|
One pointer to the one-line description string.
|
|
.It
|
|
One pointer to the list of filenames.
|
|
.El
|
|
.It
|
|
For each page, the list of names.
|
|
Each name is preceded by a single byte indicating the sources of the name.
|
|
The meaning of the bits is:
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
0x10: The name appears in a filename.
|
|
.It
|
|
0x08: The name appears in a header line, i.e. in a .Dt or .TH macro.
|
|
.It
|
|
0x04: The name is the first one in the title line, i.e. it appears
|
|
in the first .Nm macro in the NAME section.
|
|
.It
|
|
0x02: The name appears in any .Nm macro in the NAME section.
|
|
.It
|
|
0x01: The name appears in an .Nm block in the SYNOPSIS section.
|
|
.El
|
|
.It
|
|
For each page, the list of sections.
|
|
Each section is given as a string, not as a number.
|
|
.It
|
|
For each architecture-dependent page, the list of architectures.
|
|
.It
|
|
For each page, the one-line description string taken from the .Nd macro.
|
|
.It
|
|
For each page, the list of filenames relative to the root of the
|
|
respective manpath.
|
|
This list includes hard links, soft links, and links simulated
|
|
with .so
|
|
.Xr roff 7
|
|
requests.
|
|
The first filename is preceded by a single byte
|
|
having the following significance:
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
.Dv FORM_SRC No = 0x01 :
|
|
The file format is
|
|
.Xr mdoc 7
|
|
or
|
|
.Xr man 7 .
|
|
.It
|
|
.Dv FORM_CAT No = 0x02 :
|
|
The manual page is preformatted.
|
|
.El
|
|
.It
|
|
Zero to three NUL bytes for padding.
|
|
.El
|
|
.Pp
|
|
The macros table consists of:
|
|
.Pp
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
The number of different macro keys, currently 36.
|
|
The ordering of macros is defined in
|
|
.In mansearch.h
|
|
and the significance of the macro keys is documented in
|
|
.Xr apropos 1 .
|
|
.It
|
|
For each macro key, one pointer to the respective macro table.
|
|
.It
|
|
For each macro key, the macro table (variable length).
|
|
.El
|
|
.Pp
|
|
Each macro table consists of:
|
|
.Pp
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
The number of entries in the table.
|
|
.It
|
|
For each entry:
|
|
.Bl -dash -compact -offset 2n -width 1n
|
|
.It
|
|
One pointer to the value of the macro key.
|
|
Each value is a string of text taken from some macro invocation.
|
|
.It
|
|
One pointer to the list of pages.
|
|
.El
|
|
.It
|
|
For each entry, the value of the macro key.
|
|
.It
|
|
Zero to three NUL bytes for padding.
|
|
.It
|
|
For each entry, one or more pointers to pages in the pages table,
|
|
pointing to the pointer to the list of names,
|
|
followed by the number 0.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/man/mandoc.db -compact
|
|
.It Pa /usr/share/man/mandoc.db
|
|
The manual page database for the base system.
|
|
.It Pa /usr/X11R6/man/mandoc.db
|
|
The same for the
|
|
.Xr X 7
|
|
Window System.
|
|
.It Pa /usr/local/man/mandoc.db
|
|
The same for
|
|
.Xr packages 7 .
|
|
.El
|
|
.Pp
|
|
A program to dump
|
|
.Nm
|
|
files in a human-readable format suitable for
|
|
.Xr diff 1
|
|
is provided in the directory
|
|
.Pa /usr/src/regress/usr.bin/mandoc/db/dbm_dump/ .
|
|
.Sh SEE ALSO
|
|
.Xr apropos 1 ,
|
|
.Xr man 1 ,
|
|
.Xr whatis 1 ,
|
|
.Xr makewhatis 8
|
|
.Sh HISTORY
|
|
A manual page database
|
|
.Pa /usr/lib/whatis
|
|
first appeared in
|
|
.Bx 2 .
|
|
The present format first appeared in
|
|
.Ox 6.1 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The original version of
|
|
.Xr makewhatis 8
|
|
was written by
|
|
.An Bill Joy
|
|
in 1979.
|
|
The present database format was designed by
|
|
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
|
|
in 2016.
|