-.\" $Id: mandocdb.8,v 1.1 2011/07/14 14:36:37 schwarze Exp $
+.\" $Id: mandocdb.8,v 1.15 2011/12/25 13:08:12 schwarze Exp $
.\"
.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: July 14 2011 $
+.Dd $Mdocdate: December 25 2011 $
.Dt MANDOCDB 8
.Os
.Sh NAME
.Nd index UNIX manuals
.Sh SYNOPSIS
.Nm
-.Op Fl ruv
-.Op Fl d Ar dir
-.Ar
+.Op Fl avW
+.Op Fl C Ar file
+.Nm
+.Op Fl avW
+.Ar dir ...
+.Nm
+.Op Fl vW
+.Fl d Ar dir
+.Op Ar
+.Nm
+.Op Fl vW
+.Fl u Ar dir
+.Op Ar
+.Nm
+.Fl t Ar
.Sh DESCRIPTION
The
.Nm
utility extracts keywords from
.Ux
-manuals and indexes them for fast retrieval.
-The arguments are as follows:
-.Bl -tag -width Ds
-.It Fl d Ar dir
-The directory into which to write the keyword and index databases.
-.It Ar
-Read input from zero or more files in
-.Xr mdoc 7
-or
-.Xr man 7
-.Ux
-manual format.
-.It Fl r
-Remove entries.
-This will remove the index and keyword references.
-If the record is not found, it is ignored.
-.It Fl u
-Update the record.
-This will first remove the record (as in
-.Fl r )
-then re-add it.
-.It Fl v
-Verbose output.
-If specified once, prints the name of each indexed file.
-If twice, prints keywords for each file.
-.El
+manuals and indexes them in a
+.Sx Keyword Database
+and
+.Sx Index Database
+for fast retrieval.
.Pp
By default,
.Nm
-constructs a new
-.Sx Index Database
+creates databases in each
+.Ar dir
+using the files
+.Sm off
+.Sy man Ar section Li /
+.Op Ar arch Li /
+.Ar title . section
+.Sm on
and
-.Sx Keyword Database
-in the current working directory.
-Existing databases are truncated.
+.Sm off
+.Sy cat Ar section Li /
+.Op Ar arch Li /
+.Ar title . Sy 0
+.Sm on
+in that directory;
+existing databases are truncated.
+If
+.Ar dir
+is not provided,
+.Nm
+uses the default paths stipulated by
+.Xr man 1 .
+.Pp
+The arguments are as follows:
+.Bl -tag -width "-C file"
+.It Fl a
+Use all directories and files found below
+.Ar dir ... .
+.It Fl C Ar file
+Specify an alternative configuration
+.Ar file
+in
+.Xr man.conf 5
+format.
+.It Fl d Ar dir
+Merge (remove and re-add)
+.Ar
+to the database in
+.Ar dir
+without truncating it.
+.It Fl t Ar
+Check the given
+.Ar files
+for potential problems.
+No databases are modified.
+Implies
+.Fl a
+and
+.Fl W .
+All diagnostic messages are printed to the standard output;
+the standard error output is not used.
+.It Fl u Ar dir
+Remove
+.Ar
+from the database in
+.Ar dir
+without truncating it.
+.It Fl v
+Display all files added or removed to the index.
+.It Fl W
+Print warnings about potential problems with manual pages
+to the standard error output.
+.El
.Pp
-If fatal parse errors are encountered, the offending file is printed to
-stderr, omitted from the index, and the parse continues with the next
-input file.
+If fatal parse errors are encountered while parsing, the offending file
+is printed to stderr, omitted from the index, and the parse continues
+with the next input file.
.Ss Index Database
The index database,
.Pa mandoc.index ,
.Pp
.Bl -enum -compact
.It
-a nil-terminated filename,
+the character
+.Cm d ,
+.Cm a ,
+or
+.Cm c
+to indicate the file type
+.Po
+.Xr mdoc 7 ,
+.Xr man 7 ,
+and post-formatted, respectively
+.Pc ,
+.It
+the filename relative to the databases' path,
.It
-a nil-terminated manual section,
+the manual section,
.It
-a nil-terminated manual title,
+the manual title,
.It
-a nil-terminated architecture
-.Pq this is not often available
+the architecture
+.Pq often empty ,
.It
-and a nil-terminated description.
+and the description.
.El
.Pp
-Both the manual section and description may be zero-length.
-Entries are sequentially-numbered, but the filenames are unordered.
+Each of the above is NUL-terminated.
+.Pp
+If the record value is zero-length, it is unassigned.
.Ss Keyword Database
The keyword database,
.Pa mandoc.db ,
is a
.Xr btree 3
-database of nil-terminated keywords (record length is non-zero string
-length plus one) mapping to a 8-byte binary field consisting of the
-keyword type and source
+database of NUL-terminated keywords (record length is non-zero string
+length plus one) mapping to a 12-byte binary field consisting of the
+64-bit keyword type and 32-bit source
.Sx Index Database
-record number.
-The type, a 32-bit bit-mask in host order, consists of the following
-fields:
+record number, both in network-byte order.
+The type bit-mask consists of the following
+values mapping into
+.Xr mdoc 7
+macro identifiers:
.Pp
-.Bl -tag -width Ds -offset indent -compact
-.It Li 0x01
-The name of a manual page as given in the NAME section.
-.It Li 0x02
-A function prototype name as given in the SYNOPSIS section.
-.It Li 0x04
-A utility name as given in the SYNOPSIS section.
-.It Li 0x08
-An include file as given in the SYNOPSIS section.
-.It Li 0x10
-A variable name as given in the SYNOPSIS section.
-.It Li 0x20
-A standard as given in the STANDARDS section.
-.It Li 0x40
-An author as given in the AUTHORS section.
-.It Li 0x80
-A configuration as given in the SYNOPSIS section.
-.It Li 0x100
-Free-form descriptive text as given in the NAME section.
-.It Li 0x200
-Cross-links between manuals.
-Listed as the link name, then a period, then the link section.
-If the link has no section, the period terminates the string.
-.It Li 0x400
-Path reference as given in the FILES section.
-.It Li 0x800
-Environment variable as given in the ENVIRONMENT section.
-.It Li 0x1000
-Error codes as given in the ERRORS section.
+.Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
+.It Li 0x0000000000000001ULL Ta \&An
+.It Li 0x0000000000000002ULL Ta \&Ar
+.It Li 0x0000000000000004ULL Ta \&At
+.It Li 0x0000000000000008ULL Ta \&Bsx
+.It Li 0x0000000000000010ULL Ta \&Bx
+.It Li 0x0000000000000020ULL Ta \&Cd
+.It Li 0x0000000000000040ULL Ta \&Cm
+.It Li 0x0000000000000080ULL Ta \&Dv
+.It Li 0x0000000000000100ULL Ta \&Dx
+.It Li 0x0000000000000200ULL Ta \&Em
+.It Li 0x0000000000000400ULL Ta \&Er
+.It Li 0x0000000000000800ULL Ta \&Ev
+.It Li 0x0000000000001000ULL Ta \&Fa
+.It Li 0x0000000000002000ULL Ta \&Fl
+.It Li 0x0000000000004000ULL Ta \&Fn
+.It Li 0x0000000000008000ULL Ta \&Ft
+.It Li 0x0000000000010000ULL Ta \&Fx
+.It Li 0x0000000000020000ULL Ta \&Ic
+.It Li 0x0000000000040000ULL Ta \&In
+.It Li 0x0000000000080000ULL Ta \&Lb
+.It Li 0x0000000000100000ULL Ta \&Li
+.It Li 0x0000000000200000ULL Ta \&Lk
+.It Li 0x0000000000400000ULL Ta \&Ms
+.It Li 0x0000000000800000ULL Ta \&Mt
+.It Li 0x0000000001000000ULL Ta \&Nd
+.It Li 0x0000000002000000ULL Ta \&Nm
+.It Li 0x0000000004000000ULL Ta \&Nx
+.It Li 0x0000000008000000ULL Ta \&Ox
+.It Li 0x0000000010000000ULL Ta \&Pa
+.It Li 0x0000000020000000ULL Ta \&Rs
+.It Li 0x0000000040000000ULL Ta \&Sh
+.It Li 0x0000000080000000ULL Ta \&Ss
+.It Li 0x0000000100000000ULL Ta \&St
+.It Li 0x0000000200000000ULL Ta \&Sy
+.It Li 0x0000000400000000ULL Ta \&Tn
+.It Li 0x0000000800000000ULL Ta \&Va
+.It Li 0x0000001000000000ULL Ta \&Vt
+.It Li 0x0000002000000000ULL Ta \&Xr
.El
.Pp
The last four bytes are a host-ordered record number within the
.Sx Index Database .
-.Pp
-The
-.Nm
-utility is
-.Ud
.Sh IMPLEMENTATION NOTES
The time to construct a new database pair grows linearly with the
-number of keywords in the input.
+number of keywords in the input files.
However, removing or updating entries with
-.Fl r
+.Fl u
or
-.Fl u ,
+.Fl d ,
respectively, grows as a multiple of the index length and input size.
.Sh FILES
.Bl -tag -width Ds
A
.Xr recno 3
database of indexed file-names.
+.It Pa /etc/man.conf
+The default
+.Xr man 1
+configuration file.
.El
.Sh EXIT STATUS
The
to exit at once, possibly in the middle of parsing or formatting a file.
The output databases are corrupt and should be removed .
.El
+.Sh DIAGNOSTICS
+If the following errors occur, the
+.Nm
+databases should be rebuilt.
+.Bl -diag
+.It "%s: Corrupt database"
+The keyword database file indicated by
+.Pa %s
+is unreadable.
+.It "%s: Corrupt index"
+The index database file indicated by
+.Pa %s
+is unreadable.
+.It "%s: Path too long"
+The file
+.Pa %s
+is too long.
+This usually indicates database corruption or invalid command-line
+arguments.
+.El
.Sh SEE ALSO
-.Xr mandoc 1
+.Xr apropos 1 ,
+.Xr man 1 ,
+.Xr whatis 1 ,
+.Xr btree 3 ,
+.Xr recno 3 ,
+.Xr man.conf 5
.Sh AUTHORS
The
.Nm
utility was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blobdiff