Annotation of mandoc/man.conf.5, Revision 1.6
1.6 ! schwarze 1: .\" $Id: man.conf.5,v 1.5 2017/08/22 18:17:52 schwarze Exp $
1.1 schwarze 2: .\"
1.6 ! schwarze 3: .\" Copyright (c) 2015, 2017 Ingo Schwarze <schwarze@openbsd.org>
1.1 schwarze 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.6 ! schwarze 17: .Dd $Mdocdate: August 22 2017 $
1.1 schwarze 18: .Dt MAN.CONF 5
19: .Os
20: .Sh NAME
21: .Nm man.conf
1.2 schwarze 22: .Nd configuration file for man
1.1 schwarze 23: .Sh DESCRIPTION
1.2 schwarze 24: This is the configuration file
25: for the
1.1 schwarze 26: .Xr man 1 ,
27: .Xr apropos 1 ,
28: and
29: .Xr makewhatis 8
30: utilities.
1.2 schwarze 31: Its presence, and all directives, are optional.
1.1 schwarze 32: .Pp
33: This file is an ASCII text file.
34: Leading whitespace on lines, lines starting with
35: .Sq # ,
36: and blank lines are ignored.
37: Words are separated by whitespace.
38: The first word on each line is the name of a configuration directive.
39: .Pp
40: The following directives are supported:
41: .Bl -tag -width Ds
42: .It Ic manpath Ar path
1.2 schwarze 43: Override the default search
1.1 schwarze 44: .Ar path
1.2 schwarze 45: for
1.1 schwarze 46: .Xr man 1 ,
47: .Xr apropos 1 ,
48: and
1.2 schwarze 49: .Xr makewhatis 8 .
50: It can be used multiple times to specify multiple paths,
51: with the order determining the manual page search order.
52: .Pp
53: Each path is a tree containing subdirectories
1.1 schwarze 54: whose names consist of the strings
55: .Sq man
56: and/or
57: .Sq cat
58: followed by the names of sections, usually single digits.
59: The former are supposed to contain unformatted manual pages in
60: .Xr mdoc 7
61: and/or
62: .Xr man 7
1.2 schwarze 63: format; file names should end with the name of the section
1.1 schwarze 64: preceded by a dot.
1.2 schwarze 65: The latter should contain preformatted manual pages;
66: file names should end with
1.1 schwarze 67: .Ql .0 .
1.2 schwarze 68: .Pp
1.1 schwarze 69: Creating a
70: .Xr mandoc.db 5
71: database with
72: .Xr makewhatis 8
73: in each directory configured with
74: .Ic manpath
75: is recommended and necessary for
76: .Xr apropos 1
1.5 schwarze 77: to work, and also for
78: .Xr man 1
79: on operating systems like
80: .Ox
81: that install each manual page with only one file name in the file system,
82: even if it documents multiple utilities or functions.
1.3 schwarze 83: .It Ic output Ar option Op Ar value
84: Configure the default value of an output option.
85: These directives are overridden by the
86: .Fl O
87: command line options of the same names.
88: For details, see the
89: .Xr mandoc 1
90: manual.
91: .Pp
92: .Bl -column fragment integer "ascii, utf8" -compact
93: .It Ar option Ta Ar value Ta used by Fl T Ta purpose
94: .It Ta Ta Ta
95: .It Ic fragment Ta none Ta Cm html Ta print only body
96: .It Ic includes Ta string Ta Cm html Ta path to header files
97: .It Ic indent Ta integer Ta Cm ascii , utf8 Ta left margin
1.4 schwarze 98: .It Ic man Ta string Ta Cm html Ta path for \&Xr links
1.3 schwarze 99: .It Ic paper Ta string Ta Cm ps , pdf Ta paper size
100: .It Ic style Ta string Ta Cm html Ta CSS file
1.6 ! schwarze 101: .It Ic toc Ta none Ta Cm html Ta print table of contents
1.3 schwarze 102: .It Ic width Ta integer Ta Cm ascii , utf8 Ta right margin
103: .El
1.1 schwarze 104: .It Ic _whatdb Ar path Ns Cm /whatis.db
105: This directive provides the same functionality as
106: .Ic manpath ,
107: but using a historic and misleading syntax.
108: It is kept for backward compatibility for now,
109: but will eventually be removed.
110: .El
111: .Sh FILES
112: .Pa /etc/man.conf
113: .Sh EXAMPLES
114: The following configuration file reproduces the defaults:
1.2 schwarze 115: installing it is equivalent to not having a
1.1 schwarze 116: .Nm
1.2 schwarze 117: file at all.
1.1 schwarze 118: .Bd -literal -offset indent
119: manpath /usr/share/man
120: manpath /usr/X11R6/man
121: manpath /usr/local/man
122: .Ed
123: .Sh SEE ALSO
124: .Xr apropos 1 ,
125: .Xr man 1 ,
126: .Xr makewhatis 8
127: .Sh HISTORY
128: A relatively complicated
129: .Nm
130: file format first appeared in
131: .Bx 4.3 Reno .
132: For
133: .Ox 5.8 ,
134: it was redesigned from scratch, aiming for simplicity.
135: .Sh AUTHORS
136: .An Ingo Schwarze Aq Mt schwarze@openbsd.org
CVSweb