Support nesting of elements with next-line scope.

[mandoc.git] / man.conf.5

diff --git a/man.conf.5 b/man.conf.5
index d5e94126d4707cd09c577186034b9ff9048fdbe2..be0998087d171a74eba2b63b66a16d0c5fe050f3 100644 (file)
--- a/man.conf.5
+++ b/man.conf.5
@@ -1,4 +1,4 @@
-.\"    $Id: man.conf.5,v 1.1 2015/03/27 00:18:14 schwarze Exp $
+.\"    $Id: man.conf.5,v 1.5 2017/08/22 18:17:52 schwarze Exp $
 .\"
 .\" Copyright (c) 2015 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,23 +14,21 @@
 .\" 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 $
+.Dd $Mdocdate: August 22 2017 $
 .Dt MAN.CONF 5
 .Os
 .Sh NAME
 .Nm man.conf
-.Nd configuration file for man(1)
+.Nd configuration file for man
 .Sh DESCRIPTION
-The
-.Nm
-configuration file allows to specify non-standard directory trees
-for use by the
+This is the configuration file
+for the
 .Xr man 1 ,
 .Xr apropos 1 ,
 and
 .Xr makewhatis 8
 utilities.
-Its presence and all directives are optional.
+Its presence, and all directives, are optional.
 .Pp
 This file is an ASCII text file.
 Leading whitespace on lines, lines starting with
@@ -42,15 +40,17 @@ The first word on each line is the name of a configuration directive.
 The following directives are supported:
 .Bl -tag -width Ds
 .It Ic manpath Ar path
-Specify that the absolute
+Override the default search
 .Ar path
-contains a tree of manual pages, and that
+for
 .Xr man 1 ,
 .Xr apropos 1 ,
 and
-.Xr makewhatis 8
-shall use it by default.
-Each such tree is supposed to contain subdirectories
+.Xr makewhatis 8 .
+It can be used multiple times to specify multiple paths,
+with the order determining the manual page search order.
+.Pp
+Each path is a tree containing subdirectories
 whose names consist of the strings
 .Sq man
 and/or
@@ -60,11 +60,12 @@ 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
+format; file names should 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
+The latter should contain preformatted manual pages;
+file names should end with
 .Ql .0 .
+.Pp
 Creating a
 .Xr mandoc.db 5
 database with
@@ -73,16 +74,32 @@ 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 .
+to work, and also for
+.Xr man 1
+on operating systems like
+.Ox
+that install each manual page with only one file name in the file system,
+even if it documents multiple utilities or functions.
+.It Ic output Ar option Op Ar value
+Configure the default value of an output option.
+These directives are overridden by the
+.Fl O
+command line options of the same names.
+For details, see the
+.Xr mandoc 1
+manual.
 .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.
+.Bl -column fragment integer "ascii, utf8" -compact
+.It Ar option   Ta Ar value Ta used by Fl T Ta purpose
+.It Ta Ta Ta
+.It Ic fragment Ta none     Ta Cm html Ta print only body
+.It Ic includes Ta string   Ta Cm html Ta path to header files
+.It Ic indent   Ta integer  Ta Cm ascii , utf8 Ta left margin
+.It Ic man      Ta string   Ta Cm html Ta path for \&Xr links
+.It Ic paper    Ta string   Ta Cm ps , pdf Ta paper size
+.It Ic style    Ta string   Ta Cm html Ta CSS file
+.It Ic width    Ta integer  Ta Cm ascii , utf8 Ta right margin
+.El
 .It Ic _whatdb Ar path Ns Cm /whatis.db
 This directive provides the same functionality as
 .Ic manpath ,
@@ -94,9 +111,9 @@ but will eventually be removed.
 .Pa /etc/man.conf
 .Sh EXAMPLES
 The following configuration file reproduces the defaults:
-Installing it is equivalent to not having a file
+installing it is equivalent to not having a
 .Nm
-at all.
+file at all.
 .Bd -literal -offset indent
 manpath /usr/share/man
 manpath /usr/X11R6/man