1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
|
README for the man-db manual pager suite
========================================
Please read the man-db manual, available in PostScript format, located at an
FTP site carrying this package. It contains configuration details and other
aspects of this manual pager suite that are not duplicated or relevant in
this README.
As of man-db-2.3.11, the man-db manual is *included* with this distribution
in source form. Please check manual/README for details of the formatters
required. The man-db manual must be built from the manual subdirectory.
Read docs/INSTALL.autoconf for generic options to configure.
Read docs/INSTALL.quick if you know all about man-db.
Read docs/NEWS for visible changes since the last public release.
Read docs/ChangeLog for details of recent source code changes.
Read docs/TODO for future plans.
The C source requires an ANSI C compiler.
Notice to users of man-db version 2.2 or 2.2.1
==============================================
If you have stray-cats and created place-holders for them with `straycats'
from the man-db-2.2 distribution, you must delete them before using
man-db-2.3 or above. (straycats v2.2 with an option of
`--delete-placeholders' will do.) man-db-2.3 or above still provides
support for stray-cats, but uses a database entry rather than a file
system i-node to indicate their presence.
Obsoleted files include $(libdir)/makewhatis, /etc/manpath.config,
$(bindir)/{getwhatis,makewhatis,straycats}, $(libdir)/globalman.*,
any user localman.* databases and the manual pages: getwhatis, makewhatis
and straycats all from section 8. The other binaries:
$(bindir)/{man,mandb,manpath,apropos,whatis} and associated manual pages
may be replaced by this version depending upon install directories.
Notice regarding current state of FHS (Linux/?BSD)
==================================================
As of May 13th, 2001, the last public release of the Filesystem Hierarchy
Standard proposed the root of the manual page hierarchy as `/usr/share' and
the root of the writable cat hierarchy as `/var/cache/man' for the purposes
of man->cat filename translation. As such, the following are defined in
./include/manconfig.h.in:
#define FHS_CAT_ROOT "/var/cache/man" /* required by fsstnd() */
#define FHS_MAN_ROOT "/usr/share" /* required by fsstnd() */
For compatibility with the old FSSTND, the following locations are also
defined:
#define CAT_ROOT "/var/catman" /* required by fsstnd() */
#define MAN_ROOT "/usr" /* required by fsstnd() */
Should these locations change, simply define the paths accordingly and
recompile. Other FHS changes relating to man/cat paths will not be
compatible with this version of man-db.
Non generic arguments to configure
==================================
To allow the configuration program, configure, to be non-interactive, it can
be passed various options to alter the default settings. Generic configure
options are discussed in docs/INSTALL.autoconf. The following list of
options is extracted from the man-db manual. It is strongly recommended
that relevant sections of the manual are read if any of these options are
used.
--enable-setuid[=ARG]
By default, man will be installed as a setuid program
to user man. Use this option with an argument to change
the setuid owner.
--disable-setuid
Use this option to install man as a non-setuid program
and to change the default cat and database files'
access flags to allow users to modify them.
--enable-mandirs=OS
By default, man-db supports manual page directories in any of several
layouts used by free and proprietary versions of UNIX. However, in cer-
tain cases, this can cause man-db to find the wrong page by mistake,
especially when the names of some manual pages on the system contain
periods. Use this option with an argument of GNU, HPUX, IRIX, Solaris,
or BSD (or more than one of these, separated by commas) to support only
the layouts typically used on each of those systems. Note that man-db is
not currently capable of writing cat pages in the proper BSD layout.
--with-device=DEVICE
Use this flag to alter the default output device used
by NROFF. DEVICE is passed to NROFF with the -T option.
configure will test that NROFF will run with the sup-
plied device argument.
--with-db=LIBRARY
configure will look for database interface libraries in
the order Berkeley DB, gdbm and finally ndbm and will
#define appropriate variables relative to the first one
found. To override the built in order on platforms hav-
ing a choice of interface library, use this option to
specify which library to use.
INSTALL
=======
Running configure.
o READ `docs/INSTALL.autoconf' regarding ./configure options
o RUN `./configure --help' to see what --enable and --with
options may be useful.
o RUN `./configure' with the appropriate options and environment
variable settings
BROWSE or EDIT the following files that were created by the configuration
process.
o `include/manconfig.h' regarding paths to support programs,
the default section list and other specific definitions.
o `include/comp_src.h' if the default compressor support is
inadequate for your requirements. (usually .Z [compress],
.z, .gz [gzip])
configure will determine your system's ability to use native language
support (NLS) message catalogues. You may set the environment variable
LINGUAS to limit the set of translations installed. LINGUAS should contain
a space-separated list of two-letter language identifiers. To compile
man-db with no support for message catalogues, simply pass the --disable-nls
option to configure. N.B. This is not related to man's ability to display
NLS manual pages, support for which is compiled in by default.
Running make.
o RUN `make' to compile man-db with the set of translations chosen
when running `./configure'.
Sort out the man-db configuration file.
o RUN `./src/man -l man/man5/manpath.5' from the root of this
distribution to read the man-db configuration file details.
o EDIT `./src/man_db.conf' to your local requirements.
Install the package.
o (gain superuser privileges for the rest of the steps)
o RUN `make install' to install the utilities and manual pages.
Initialise the `index' databases for all manpaths marked as global in the
man-db configuration file.
o RUN `mandb' (This step is equivalent to running straycats and
makewhatis too).
The following steps are optional / dependent on local conventions.
o ACKNOWLEDGE any warnings emitted by mandb. Bogus manual pages
are not included in the database and may be a waste of space.
Those pages without correctly formatted `whatis' lines are
included, but will have a whatis entry of "(unknown)"
o CD tools and RUN `mkcatdirs -t' to see if you have all of the
required cat directories. `mkcatdirs' without an option will
display a usage message.
o CD tools and RUN `checkman' with an argument of colon separated
manual page hierarchies to cross check for duplicated manual
pages. If no argument is given, your default $MANPATH will be
used.
The output of checkman may be piped into a file and used as an
argument to `rm', the `is newer than' messages are directed to
standard error. e.g. `checkman > dups'
If you are confident that the duplicates found are indeed
duplicates, you can back them up and delete them to save space.
At this point, running checkman again may yield further duplicates
that were ignored the first time.
o RUN `catman' with appropriate options to create any/all cat files
that you would like pre-formatted.
Multiple build directories
==========================
It is possible to build man-db in a directory other than the directory
containing this file (and all of the program sources). This is particularly
useful if compiling on multiple architectures or testing various
configuration options as only a single copy of the sources is required.
To enable this support, simply change directory to where you would like to
build the package and run the configure program in this directory
*from there*. Further information about this support can be found in the
generic install document `docs/INSTALL.autoconf'.
Makefile targets and variables
==============================
The standard GNU Makefile targets: all, install, uninstall, mostlyclean,
clean, distclean, realclean and TAGS are available in every Makefile-
supported directory. In addition, the master Makefile has the dist target
to create a compressed and tarred distribution file.
During the configuration process, `configure' sets the installation
variables, `prefix' and `exec_prefix'. These are then used to form other
variables such as `bindir' and `sysconfdir'. To change any of these or
other standard GNU install variables dynamically, issue the `make' command
with variable expressions as arguments, eg. `make prefix=/usr/local/packages'
N.B. If prefix=/usr (either statically or dynamically), then sysconfdir=/etc
instead of the usual $(prefix)/etc. To force sysconfdir to be /usr/etc, set
it on the make command line.
Default preprocessors
=====================
man-db uses a manual page directed preprocessor system, that is, each manual
page may request preprocessing by a selection of preprocessors. Some
systems' manual pages do not come with this information built in. In such
circumstances, it is advisable to set a default list of preprocessors that
each manual page should be passed through, so that those requiring special
processing are readable. To achieve this, set DEFAULT_MANROFFSEQ (found in
include/manconfig.h) to the appropriate preprocessor string, after running
configure, but prior to compilation. This is not necessary for the
following systems whose default preprocessing requirements are known.
Known not to require DEFAULT_MANROFFSEQ:
Linux, SunOS
Known to require #define DEFAULT_MANROFFSEQ "t":
Ultrix
Known to require #define DEFAULT_MANROFFSEQ "te":
HP-UX, OSF/1
If unsure of the default preprocessors required by a system, the standard
system's man(1) manual page may provide an answer.
System specific notes
=====================
Linux
o Public released C library distributions prior to 4.5.26 contain
no Berkeley DB interface routines and an old gdbm implementation.
It is advisable to either install a recent version of gdbm (v1.6+)
or the Berkeley DB library (v1.79+) to gain enhanced performance.
o C library distribution 4.6.20 contains a bug that requires -static
to be used as a linker option if -g and -ldb are also used. If
not, programs linked with the db library will cause a segmentation
violation on startup.
o C library distribution 4.6.27 contains a bug that causes links
with -ldb to fail completely if -g is used without -static. As
such, configure will automatically choose gdbm routines found
in the gdbm library if $CFLAGS contains -g without -static at the
time of running configure.
o The recommended ./configure command:
CFLAGS='-O2 -fomit-frame-pointer' ./configure --prefix=/usr
Ultrix-4.3a
o When compiled for BSD environment, each running `man' increases
the system load as reported by uptime(1) by one. The reason for
this behaviour is currently unknown, but the load increase does
*not* reflect actual resource usage. To avoid it, compile for
POSIX environment:
CC='cc -YPOSIX' ./configure
Contacting the maintainer
=========================
The current maintainer of man-db is Colin Watson <cjwatson@debian.org>.
Please feel free to contact me with any queries or problems you may have. If
you are using the Debian GNU/Linux or GNU/Hurd system, I welcome bug reports
against the man-db package by way of the Debian bug tracking system
(http://bugs.debian.org/).
|