Strip information that no longer applies and document new "manpath" directive.

jmc@ agrees with the general direction (but hasn't seen this draft;
let's tweak it in the tree).

3 files changed, 122 insertions, 4 deletions

diff --git a/usr.bin/man/Makefile b/usr.bin/man/Makefile
index 01b3221d0cd..35a8c0e4390 100644
--- a/usr.bin/man/Makefile
+++ b/usr.bin/man/Makefile
@@ -1,5 +1,5 @@
-#	$OpenBSD: Makefile,v 1.6 2014/12/14 17:55:36 schwarze Exp $
+#	$OpenBSD: Makefile,v 1.7 2015/03/26 23:45:37 schwarze Exp $
 
-MAN=	man.conf.5 help.1
+MAN=	help.1
 
 .include <bsd.prog.mk>
diff --git a/usr.bin/mandoc/Makefile b/usr.bin/mandoc/Makefile
index 9c434d24b29..a47a62994b1 100644
--- a/usr.bin/mandoc/Makefile
+++ b/usr.bin/mandoc/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.93 2015/03/18 18:04:12 pascal Exp $
+#	$OpenBSD: Makefile,v 1.94 2015/03/26 23:45:37 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -26,7 +26,7 @@ LINKS =	${BINDIR}/mandoc ${BINDIR}/apropos \
 	${BINDIR}/mandoc /usr/sbin/makewhatis \
 	${BINDIR}/mandoc /usr/libexec/makewhatis
 
-MAN =	apropos.1 man.1 mandoc.1 makewhatis.8
+MAN =	apropos.1 man.1 mandoc.1 man.conf.5 makewhatis.8
 MLINKS=	apropos.1 whatis.1
 
 CLEANFILES += man.cgi cgi.o
diff --git a/usr.bin/mandoc/man.conf.5 b/usr.bin/mandoc/man.conf.5
new file mode 100644
index 00000000000..09a232a7ec9
--- /dev/null
+++ b/usr.bin/mandoc/man.conf.5
@@ -0,0 +1,118 @@
+.\"	$OpenBSD: man.conf.5,v 1.1 2015/03/26 23:45:37 schwarze Exp $
+.\"
+.\" 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: March 26 2015 $
+.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