1 README for the man-db manual pager suite
2 ========================================
4 Please read the man-db manual, included in the manual subdirectory of this
5 distribution. It contains configuration details and other aspects of this
6 manual pager suite that are not duplicated or relevant in this README.
7 Check manual/README for details of the formatters required.
9 Read docs/INSTALL.autoconf for generic options to configure.
10 Read docs/INSTALL.quick if you know all about man-db.
11 Read NEWS for visible changes since the last public release.
12 Read ChangeLog for details of recent source code changes.
13 Read docs/TODO for future plans.
15 The C source requires an ANSI C compiler.
18 Copyright and licensing
19 =======================
21 Copyright (C) 1990, 1991 John W. Eaton.
22 Copyright (C) 1994, 1995 Markus Armbruster.
23 Copyright (C) 1994, 1995 Graeme W. Wilford. (Wilf.)
24 Copyright (C) 1995 Carl Edman.
25 Copyright (C) 1996, 1997, 1998, 2000 Fabrizio Polacco.
26 Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
27 2011, 2012 Colin Watson.
28 Copyright (C) 1984, 1989, 1990, 1991, 1992, 1995, 1996, 1997, 1998, 1999,
29 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
30 2010, 2011, 2012 Free Software Foundation, Inc.
32 man-db is free software; you can redistribute it and/or modify it
33 under the terms of the GNU General Public License as published by
34 the Free Software Foundation; either version 2 of the License, or
35 (at your option) any later version.
37 man-db is distributed in the hope that it will be useful, but
38 WITHOUT ANY WARRANTY; without even the implied warranty of
39 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
40 GNU General Public License for more details.
42 You should have received a copy of the GNU General Public License
43 along with man-db; if not, write to the Free Software Foundation,
44 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
46 In addition, man-db incorporates Gnulib, copyrighted by the Free Software
47 Foundation and others. Note that much of Gnulib is distributed under the GNU
48 General Public License version 3 or later. This means that, although
49 man-db's own source code is licensed under GPL v2 or later, the work as a
50 whole falls under the terms of the GPL v3 or later. Unless you take special
51 pains to remove the GPL v3 portions, you must therefore follow the terms and
52 conditions of the GPL v3 or later when distributing man-db.
55 Notice regarding current state of FHS (Linux/?BSD)
56 ==================================================
58 As of May 13th, 2001, the last public release of the Filesystem Hierarchy
59 Standard proposed the root of the manual page hierarchy as `/usr/share' and
60 the root of the writable cat hierarchy as `/var/cache/man' for the purposes
61 of man->cat filename translation. As such, the following are defined in
62 ./include/manconfig.h.in:
64 #define FHS_CAT_ROOT "/var/cache/man" /* required by fsstnd() */
65 #define FHS_MAN_ROOT "/usr/share" /* required by fsstnd() */
67 For compatibility with the old FSSTND, the following locations are also
70 #define CAT_ROOT "/var/catman" /* required by fsstnd() */
71 #define MAN_ROOT "/usr" /* required by fsstnd() */
73 Should these locations change, simply define the paths accordingly and
74 recompile. Other FHS changes relating to man/cat paths will not be
75 compatible with this version of man-db.
77 Non-generic arguments to configure
78 ==================================
80 To allow the configuration program, configure, to be non-interactive, it can
81 be passed various options to alter the default settings. Generic configure
82 options are discussed in docs/INSTALL.autoconf. The following list of
83 options is extracted from the man-db manual. It is strongly recommended
84 that relevant sections of the manual are read if any of these options are
88 By default, man will be installed as a setuid program to user man. Use
89 this option with an argument to change the setuid owner.
92 Use this option to install man as a non-setuid program and to change the
93 default cat and database files' access flags to allow users to modify
97 By default, man-db supports manual page directories in any of several
98 layouts used by free and proprietary versions of UNIX. However, in
99 certain cases, this can cause man-db to find the wrong page by mistake,
100 especially when the names of some manual pages on the system contain
101 periods. Use this option with an argument of GNU, HPUX, IRIX, Solaris,
102 or BSD (or more than one of these, separated by commas) to support only
103 the layouts typically used on each of those systems. Note that man-db is
104 not currently capable of writing cat pages in the proper BSD layout.
107 Use this flag to alter the default output device used by NROFF. DEVICE is
108 passed to NROFF with the -T option. configure will test that NROFF will
109 run with the supplied device argument.
112 configure will look for database interface libraries in the order gdbm,
113 Berkeley DB and finally ndbm and will #define appropriate variables
114 relative to the first one found. To override the built-in order on
115 platforms having a choice of interface library, use this option to
116 specify which library to use.
118 --enable-automatic-create
119 If this flag is used, man will automatically create index databases for
120 users' private manual page hierarchies.
122 --disable-automatic-update
123 Normally, man will update entries in index databases if it finds newly
124 installed manual pages (if the --update flag is used) or delete entries
125 if manual pages are removed. This flag suppresses this behaviour.
128 Normally, man will automatically try to create cat files corresponding to
129 manual files when a manual page is read. This flag suppresses this
138 o READ `docs/INSTALL.autoconf' regarding ./configure options
140 o RUN `./configure --help' to see what --enable and --with
141 options may be useful.
143 o RUN `./configure' with the appropriate options and environment
146 BROWSE or EDIT the following files that were created by the configuration
149 o `include/manconfig.h' regarding paths to support programs,
150 the default section list and other specific definitions.
152 o `include/comp_src.h' if the default compressor support is
153 inadequate for your requirements. (usually .Z [compress],
156 configure will determine your system's ability to use native language
157 support (NLS) message catalogues. You may set the environment variable
158 LINGUAS to limit the set of translations installed. LINGUAS should contain
159 a space-separated list of two-letter language identifiers. To compile
160 man-db with no support for message catalogues, simply pass the --disable-nls
161 option to configure. N.B. This is not related to man's ability to display
162 NLS manual pages, support for which is compiled in by default.
166 o RUN `make' to compile man-db with the set of translations chosen
167 when running `./configure'.
169 Sort out the man-db configuration file.
171 o RUN `./src/man -l man/man5/manpath.5' from the root of this
172 distribution to read the man-db configuration file details.
174 o EDIT `./src/man_db.conf' to your local requirements.
178 o (gain superuser privileges for the rest of the steps)
180 o RUN `make install' to install the utilities and manual pages.
182 Initialise the `index' databases for all manpaths marked as global in the
183 man-db configuration file.
185 o RUN `mandb' (This step is equivalent to running straycats and
188 The following steps are optional / dependent on local conventions.
190 o ACKNOWLEDGE any warnings emitted by mandb. Bogus manual pages
191 are not included in the database and may be a waste of space.
192 Those pages without correctly formatted `whatis' lines are
193 included, but will have a whatis entry of "(unknown)"
195 o CD tools and RUN `mkcatdirs -t' to see if you have all of the
196 required cat directories. `mkcatdirs' without an option will
197 display a usage message.
199 o CD tools and RUN `checkman' with an argument of colon separated
200 manual page hierarchies to cross check for duplicated manual
201 pages. If no argument is given, your default $MANPATH will be
204 The output of checkman may be piped into a file and used as an
205 argument to `rm', the `is newer than' messages are directed to
206 standard error. e.g. `checkman > dups'
208 If you are confident that the duplicates found are indeed
209 duplicates, you can back them up and delete them to save space.
211 At this point, running checkman again may yield further duplicates
212 that were ignored the first time.
214 o RUN `catman' with appropriate options to create any/all cat files
215 that you would like pre-formatted.
218 Multiple build directories
219 ==========================
221 It is possible to build man-db in a directory other than the directory
222 containing this file (and all of the program sources). This is particularly
223 useful if compiling on multiple architectures or testing various
224 configuration options as only a single copy of the sources is required.
226 To enable this support, simply change directory to where you would like to
227 build the package and run the configure program in this directory
228 *from there*. Further information about this support can be found in the
229 generic install document `docs/INSTALL.autoconf'.
232 Makefile targets and variables
233 ==============================
235 The standard GNU Makefile targets: all, install, uninstall, mostlyclean,
236 clean, distclean, realclean and TAGS are available in every Makefile-
237 supported directory. In addition, the master Makefile has the dist target
238 to create a compressed and tarred distribution file.
240 During the configuration process, `configure' sets the installation
241 variables, `prefix' and `exec_prefix'. These are then used to form other
242 variables such as `bindir' and `sysconfdir'. To change any of these or
243 other standard GNU install variables dynamically, issue the `make' command
244 with variable expressions as arguments, eg. `make prefix=/usr/local/packages'
246 N.B. If prefix=/usr (either statically or dynamically), then sysconfdir=/etc
247 instead of the usual $(prefix)/etc. To force sysconfdir to be /usr/etc, set
248 it on the make command line.
251 Default preprocessors
252 =====================
254 man-db uses a manual page directed preprocessor system, that is, each manual
255 page may request preprocessing by a selection of preprocessors. Some
256 systems' manual pages do not come with this information built in. In such
257 circumstances, it is advisable to set a default list of preprocessors that
258 each manual page should be passed through, so that those requiring special
259 processing are readable. To achieve this, set DEFAULT_MANROFFSEQ (found in
260 include/manconfig.h) to the appropriate preprocessor string, after running
261 configure, but prior to compilation. This is not necessary for the
262 following systems whose default preprocessing requirements are known.
264 Known not to require DEFAULT_MANROFFSEQ:
266 Known to require #define DEFAULT_MANROFFSEQ "t":
268 Known to require #define DEFAULT_MANROFFSEQ "te":
271 If unsure of the default preprocessors required by a system, the standard
272 system's man(1) manual page may provide an answer.
275 Contacting the maintainer
276 =========================
278 The current maintainer of man-db is Colin Watson <cjwatson@debian.org>.
279 Please feel free to contact me with any queries or problems you may have. If
280 you are using the Debian GNU/Linux or GNU/Hurd system, I welcome bug reports
281 against the man-db package by way of the Debian bug tracking system
282 (http://bugs.debian.org/).