diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 286 |
1 files changed, 286 insertions, 0 deletions
@@ -0,0 +1,286 @@ +README for the man-db manual pager suite +======================================== + +Please read the man-db manual, included in the manual subdirectory of this +distribution. It contains configuration details and other aspects of this +manual pager suite that are not duplicated or relevant in this README. +Check manual/README for details of the formatters required. + +Read docs/INSTALL.autoconf for generic options to configure. +Read docs/INSTALL.quick if you know all about man-db. +Read NEWS for visible changes since the last public release. +Read ChangeLog for details of recent source code changes. +Read docs/TODO for future plans. + +The C source requires an ANSI C compiler. + + +Copyright and licensing +======================= + +Copyright (C) 1990, 1991 John W. Eaton. +Copyright (C) 1994, 1995 Markus Armbruster. +Copyright (C) 1994, 1995 Graeme W. Wilford. (Wilf.) +Copyright (C) 1995 Carl Edman. +Copyright (C) 1996, 1997, 1998, 2000 Fabrizio Polacco. +Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, + 2011, 2012, 2013, 2014 Colin Watson. +Copyright (C) 1984, 1989, 1990, 1991, 1992, 1995, 1996, 1997, 1998, 1999, + 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, + 2010, 2011, 2012 Free Software Foundation, Inc. + +man-db is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +man-db is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with man-db; if not, write to the Free Software Foundation, +Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + +In addition, man-db incorporates Gnulib, copyrighted by the Free Software +Foundation and others. Note that much of Gnulib is distributed under the GNU +General Public License version 3 or later. This means that, although +man-db's own source code is licensed under GPL v2 or later, the work as a +whole falls under the terms of the GPL v3 or later. Unless you take special +pains to remove the GPL v3 portions, you must therefore follow the terms and +conditions of the GPL v3 or later when distributing man-db. + + +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-cache-owner[=ARG] + By default, system-wide cache files will be owned by user man. Use this + option with an argument to change the cache file owner. + +--disable-cache-owner + Use this option to leave the ownership of system-wide cache files + unconstrained. Users will be allowed to modify them. + +--disable-setuid + By default, man will be installed as a setuid program to the user that + owns the system-wide cache files. Use this option to install man as a + non-setuid program instead. + +--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 + certain 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 supplied device argument. + +--with-db=LIBRARY + configure will look for database interface libraries in the order gdbm, + Berkeley DB and finally ndbm and will #define appropriate variables + relative to the first one found. To override the built-in order on + platforms having a choice of interface library, use this option to + specify which library to use. + +--enable-automatic-create + If this flag is used, man will automatically create index databases for + users' private manual page hierarchies. + +--disable-automatic-update + Normally, man will update entries in index databases if it finds newly + installed manual pages (if the --update flag is used) or delete entries + if manual pages are removed. This flag suppresses this behaviour. + +--disable-cats + Normally, man will automatically try to create cat files corresponding to + manual files when a manual page is read. This flag suppresses this + behaviour. + + +INSTALL +======= + +Running configure. + + * READ `docs/INSTALL.autoconf' regarding ./configure options + + * RUN `./configure --help' to see what --enable and --with + options may be useful. + + * RUN `./configure' with the appropriate options and environment + variable settings + +BROWSE or EDIT the following files that were created by the configuration +process. + + * `include/manconfig.h' regarding paths to support programs, + the default section list and other specific definitions. + + * `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. + + * RUN `make' to compile man-db with the set of translations chosen + when running `./configure'. + +Sort out the man-db configuration file. + + * RUN `./src/man -l man/man5/manpath.5' from the root of this + distribution to read the man-db configuration file details. + + * EDIT `./src/man_db.conf' to your local requirements. + +Install the package. + + * (gain superuser privileges for the rest of the steps) + + * 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. + + * RUN `mandb' (This step is equivalent to running straycats and + makewhatis too). + +The following steps are optional / dependent on local conventions. + + * 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)" + + * 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. + + * 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. + + * 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. + + +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 +(https://bugs.debian.org/). |