Add man.conf(5). After adding some additional functionality,

one of the next steps will be to use it in addition to manpath(1)
rather than as an alternative to it.

1 files changed, 118 insertions, 0 deletions

diff --git a/man.conf.5 b/man.conf.5
new file mode 100644
index 00000000..4a670c18
--- /dev/null
+++ b/man.conf.5
@@ -0,0 +1,118 @@
+.\"	$Id$
+.\"
+.\" Copyright (c) 2015 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 $Mdocdate$
+.Dt MAN.CONF 5
+.Os
+.Sh NAME
+.Nm man.conf
+.Nd configuration file for man(1)
+.Sh DESCRIPTION
+The
+.Nm
+configuration file allows to specify non-standard directory trees
+for use by the
+.Xr man 1 ,
+.Xr apropos 1 ,
+and
+.Xr makewhatis 8
+utilities.
+Its presence and all directives are optional.
+.Pp
+This file is an ASCII text file.
+Leading whitespace on lines, lines starting with
+.Sq # ,
+and blank lines are ignored.
+Words are separated by whitespace.
+The first word on each line is the name of a configuration directive.
+.Pp
+The following directives are supported:
+.Bl -tag -width Ds
+.It Ic manpath Ar path
+Specify that the absolute
+.Ar path
+contains a tree of manual pages, and that
+.Xr man 1 ,
+.Xr apropos 1 ,
+and
+.Xr makewhatis 8
+shall use it by default.
+Each such tree is supposed to contain subdirectories
+whose names consist of the strings
+.Sq man
+and/or
+.Sq cat
+followed by the names of sections, usually single digits.
+The former are supposed to contain unformatted manual pages in
+.Xr mdoc 7
+and/or
+.Xr man 7
+format; file names are supposed to end with the name of the section
+preceded by a dot.
+The latter are supposed to contain preformatted manual pages;
+file names are supposed to end with
+.Ql .0 .
+Creating a
+.Xr mandoc.db 5
+database with
+.Xr makewhatis 8
+in each directory configured with
+.Ic manpath
+is recommended and necessary for
+.Xr apropos 1
+to work, but not strictly required for
+.Xr man 1 .
+.Pp
+Specifying at least one
+.Ic manpath
+directive does not append to the default search path
+but instead overrides it.
+The order of
+.Ic manpath
+directives determines the manual page search order.
+.It Ic _whatdb Ar path Ns Cm /whatis.db
+This directive provides the same functionality as
+.Ic manpath ,
+but using a historic and misleading syntax.
+It is kept for backward compatibility for now,
+but will eventually be removed.
+.El
+.Sh FILES
+.Pa /etc/man.conf
+.Sh EXAMPLES
+The following configuration file reproduces the defaults:
+Installing it is equivalent to not having a file
+.Nm
+at all.
+.Bd -literal -offset indent
+manpath /usr/share/man
+manpath /usr/X11R6/man
+manpath /usr/local/man
+.Ed
+.Sh SEE ALSO
+.Xr apropos 1 ,
+.Xr man 1 ,
+.Xr makewhatis 8
+.Sh HISTORY
+A relatively complicated
+.Nm
+file format first appeared in
+.Bx 4.3 Reno .
+For
+.Ox 5.8 ,
+it was redesigned from scratch, aiming for simplicity.
+.Sh AUTHORS
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org