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.

4 files changed, 132 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index 231b4161..8497ae1a 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-# $Id: Makefile,v 1.458 2015/03/19 14:57:29 schwarze Exp $
+# $Id: Makefile,v 1.459 2015/03/27 00:18:14 schwarze Exp $
 #
 # Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 # Copyright (c) 2011, 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
@@ -131,6 +131,7 @@ DISTFILES	 = INSTALL \
 		   man.1 \
 		   man.7 \
 		   man.cgi.8 \
+		   man.conf.5 \
 		   man.h \
 		   mandoc.1 \
 		   mandoc.3 \
@@ -257,6 +258,7 @@ WWW_MANS	 = apropos.1.html \
 		   mansearch.3.html \
 		   mchars_alloc.3.html \
 		   tbl.3.html \
+		   man.conf.5.html \
 		   mandoc.db.5.html \
 		   eqn.7.html \
 		   man.7.html \
@@ -320,6 +322,7 @@ base-install: base-build
 	mkdir -p $(DESTDIR)$(INCLUDEDIR)
 	mkdir -p $(DESTDIR)$(MANDIR)/man1
 	mkdir -p $(DESTDIR)$(MANDIR)/man3
+	mkdir -p $(DESTDIR)$(MANDIR)/man5
 	mkdir -p $(DESTDIR)$(MANDIR)/man7
 	$(INSTALL_PROGRAM) mandoc demandoc $(DESTDIR)$(BINDIR)
 	ln -f $(DESTDIR)$(BINDIR)/mandoc $(DESTDIR)$(BINDIR)/$(BINM_MAN)
@@ -330,6 +333,7 @@ base-install: base-build
 	$(INSTALL_MAN) man.1 $(DESTDIR)$(MANDIR)/man1/$(BINM_MAN).1
 	$(INSTALL_MAN) mandoc.3 mandoc_escape.3 mandoc_malloc.3 \
 		mchars_alloc.3 tbl.3 $(DESTDIR)$(MANDIR)/man3
+	$(INSTALL_MAN) man.conf.5 $(DESTDIR)$(MANDIR)/man5/${MANM_MANCONF}.5
 	$(INSTALL_MAN) man.7 $(DESTDIR)$(MANDIR)/man7/${MANM_MAN}.7
 	$(INSTALL_MAN) mdoc.7 $(DESTDIR)$(MANDIR)/man7/${MANM_MDOC}.7
 	$(INSTALL_MAN) roff.7 $(DESTDIR)$(MANDIR)/man7/${MANM_ROFF}.7
diff --git a/configure b/configure
index 0e20da5e..87db2897 100755
--- a/configure
+++ b/configure
@@ -82,6 +82,7 @@ BINM_MAN="man"
 BINM_WHATIS="whatis"
 BINM_MAKEWHATIS="makewhatis"
 MANM_MAN="man"
+MANM_MANCONF="man.conf"
 MANM_MDOC="mdoc"
 MANM_ROFF="roff"
 MANM_EQN="eqn"
@@ -279,6 +280,7 @@ __HEREDOC__
 [ ${HAVE_FGETLN} -eq 0 ] && echo "#include <stdio.h>"
 
 echo
+echo "#define MAN_CONF_FILE \"/etc/${MANM_MANCONF}\""
 echo "#define MANPATH_DEFAULT \"${MANPATH_DEFAULT}\""
 [ -n "${OSNAME}" ] && echo "#define OSNAME \"${OSNAME}\""
 [ -n "${HOMEBREWDIR}" ] && echo "#define HOMEBREWDIR \"${HOMEBREWDIR}\""
@@ -422,6 +424,7 @@ BINM_MAN	= ${BINM_MAN}
 BINM_WHATIS	= ${BINM_WHATIS}
 BINM_MAKEWHATIS	= ${BINM_MAKEWHATIS}
 MANM_MAN	= ${MANM_MAN}
+MANM_MANCONF	= ${MANM_MANCONF}
 MANM_MDOC	= ${MANM_MDOC}
 MANM_ROFF	= ${MANM_ROFF}
 MANM_EQN	= ${MANM_EQN}
diff --git a/configure.local.example b/configure.local.example
index cf30c9af..3cee71c4 100644
--- a/configure.local.example
+++ b/configure.local.example
@@ -1,4 +1,4 @@
-# $Id: configure.local.example,v 1.7 2015/03/22 18:14:30 schwarze Exp $
+# $Id: configure.local.example,v 1.8 2015/03/27 00:18:14 schwarze Exp $
 #
 # Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
 #
@@ -96,6 +96,11 @@ HAVE_MANPATH=1
 # man(1), makewhatis(8), and apropos(1) will not work properly.
 HAVE_MANPATH=0
 
+# Some distributions may want to avoid naming conflicts
+# with the configuration files of other man(1) implementations.
+# This changes the name of the installed section 5 manual page as well.
+MANM_MANCONF="mandoc.conf"	# default is "man.conf"
+
 # Some distributions may want to avoid naming conflicts among manuals.
 # If you want to change the names of installed section 7 manual pages,
 # the following alternative names are suggested.
diff --git a/man.conf.5 b/man.conf.5
new file mode 100644
index 00000000..d5e94126
--- /dev/null
+++ b/man.conf.5
@@ -0,0 +1,118 @@
+.\"	$Id: man.conf.5,v 1.1 2015/03/27 00:18:14 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 27 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