README for the man_db manual pager suite, version 2.3.x ======================================================= 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 and does not require use of ./configure. 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. This package _requires_ GNU make version 3.68 or newer to be used. Other vendors' make programs will not work with the Makefiles in this package due to extensive utilization of GNU make features. The C source requires an ANSI C compiler. To generate dependencies (only necessary if developing or source level debugging), a cpp that understands -M is required. 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. (straycats v2.2 with an option of `--delete-placeholders' will do). man_db-2.3 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-debug By default, the configuration process creates produc- tion quality Makefiles. This option, which takes no argument, changes certain values to aid in debugging man_db-2.3.x. It does not alter the physical behaviour of any of the programs. --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-2.3.x supports manual page directo- ries in any of several layouts used by free and propri- etary versions of UNIX. However, in certain cases, this can cause man_db-2.3.x 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, Solaris, or IRIX (or more than one of these, separated by commas) to support only the layouts typically used on each of those systems. --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/Defines' regarding general definitions used by all Makefiles in the distribution 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 English manual pages. The following command is required if you elected to compile the package without support for message catalogues but would like to install native language manual page translations. o RUN `make man targets=install LINGUAS=' to install translations of the standard English 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-2.3 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 targets: update (update any configuration files whose source has changed) and dist (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 . 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/).