README

   1 README for the man-db manual pager suite
   2 ========================================
   3
   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.
   8
   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.
  14
  15 The C source requires an ANSI C compiler.
  16
  17
  18 Copyright and licensing
  19 =======================
  20
  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, 2013, 2014 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.
  31
  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.
  36
  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.
  41
  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
  45
  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.
  53
  54
  55 Notice regarding current state of FHS (Linux/?BSD)
  56 ==================================================
  57
  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:
  63
  64 #define FHS_CAT_ROOT    "/var/cache/man"        /* required by fsstnd() */
  65 #define FHS_MAN_ROOT    "/usr/share"            /* required by fsstnd() */
  66
  67 For compatibility with the old FSSTND, the following locations are also
  68 defined:
  69
  70 #define CAT_ROOT        "/var/catman"           /* required by fsstnd() */
  71 #define MAN_ROOT        "/usr"                  /* required by fsstnd() */
  72
  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.
  76
  77 Non-generic arguments to configure
  78 ==================================
  79
  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
  85 used.
  86
  87 --enable-cache-owner[=ARG]
  88      By default, system-wide cache files will be owned by user man.  Use this
  89      option with an argument to change the cache file owner.
  90
  91 --disable-cache-owner
  92      Use this option to leave the ownership of system-wide cache files
  93      unconstrained.  Users will be allowed to modify them.
  94
  95 --disable-setuid
  96      By default, man will be installed as a setuid program to the user that
  97      owns the system-wide cache files.  Use this option to install man as a
  98      non-setuid program instead.
  99
 100 --enable-mandirs=OS
 101      By default, man-db supports manual page directories in any of several
 102      layouts used by free and proprietary versions of UNIX.  However, in
 103      certain cases, this can cause man-db to find the wrong page by mistake,
 104      especially when the names of some manual pages on the system contain
 105      periods.  Use this option with an argument of GNU, HPUX, IRIX, Solaris,
 106      or BSD (or more than one of these, separated by commas) to support only
 107      the layouts typically used on each of those systems.  Note that man-db is
 108      not currently capable of writing cat pages in the proper BSD layout.
 109
 110 --with-device=DEVICE
 111      Use this flag to alter the default output device used by NROFF. DEVICE is
 112      passed to NROFF with the -T option.  configure will test that NROFF will
 113      run with the supplied device argument.
 114
 115 --with-db=LIBRARY
 116      configure will look for database interface libraries in the order gdbm,
 117      Berkeley DB and finally ndbm and will #define appropriate variables
 118      relative to the first one found.  To override the built-in order on
 119      platforms having a choice of interface library, use this option to
 120      specify which library to use.
 121
 122 --enable-automatic-create
 123      If this flag is used, man will automatically create index databases for
 124      users' private manual page hierarchies.
 125
 126 --disable-automatic-update
 127      Normally, man will update entries in index databases if it finds newly
 128      installed manual pages (if the --update flag is used) or delete entries
 129      if manual pages are removed.  This flag suppresses this behaviour.
 130
 131 --disable-cats
 132      Normally, man will automatically try to create cat files corresponding to
 133      manual files when a manual page is read.  This flag suppresses this
 134      behaviour.
 135
 136 --disable-manual
 137      Don't build or install the man-db manual.  This may be useful when
 138      cross-compiling, or to reduce the installation size.
 139
 140
 141 INSTALL
 142 =======
 143
 144 Running configure.
 145
 146         * READ `docs/INSTALL.autoconf' regarding ./configure options
 147
 148         * RUN `./configure --help' to see what --enable and --with
 149           options may be useful.
 150
 151         * RUN `./configure' with the appropriate options and environment
 152           variable settings
 153
 154 BROWSE or EDIT the following files that were created by the configuration
 155 process.
 156
 157         * `include/manconfig.h' regarding paths to support programs,
 158           the default section list and other specific definitions.
 159
 160         * `include/comp_src.h' if the default compressor support is
 161           inadequate for your requirements.  (usually .Z [compress],
 162           .z, .gz [gzip])
 163
 164 configure will determine your system's ability to use native language
 165 support (NLS) message catalogues.  You may set the environment variable
 166 LINGUAS to limit the set of translations installed.  LINGUAS should contain
 167 a space-separated list of two-letter language identifiers.  To compile
 168 man-db with no support for message catalogues, simply pass the --disable-nls
 169 option to configure.  N.B. This is not related to man's ability to display
 170 NLS manual pages, support for which is compiled in by default.
 171
 172 Running make.
 173
 174         * RUN `make' to compile man-db with the set of translations chosen
 175           when running `./configure'.
 176
 177 Sort out the man-db configuration file.
 178
 179         * RUN `./src/man -l man/man5/manpath.5' from the root of this
 180           distribution to read the man-db configuration file details.
 181
 182         * EDIT `./src/man_db.conf' to your local requirements.
 183
 184 Install the package.
 185
 186         * (gain superuser privileges for the rest of the steps)
 187
 188         * RUN `make install' to install the utilities and manual pages.
 189
 190 Initialise the `index' databases for all manpaths marked as global in the
 191 man-db configuration file.
 192
 193         * RUN `mandb' (This step is equivalent to running straycats and
 194           makewhatis too).
 195
 196 The following steps are optional / dependent on local conventions.
 197
 198         * ACKNOWLEDGE any warnings emitted by mandb. Bogus manual pages
 199           are not included in the database and may be a waste of space.
 200           Those pages without correctly formatted `whatis' lines are
 201           included, but will have a whatis entry of "(unknown)"
 202
 203         * CD tools and RUN `mkcatdirs -t' to see if you have all of the
 204           required cat directories.  `mkcatdirs' without an option will
 205           display a usage message.
 206
 207         * CD tools and RUN `checkman' with an argument of colon separated
 208           manual page hierarchies to cross check for duplicated manual
 209           pages.  If no argument is given, your default $MANPATH will be
 210           used.
 211
 212           The output of checkman may be piped into a file and used as an
 213           argument to `rm', the `is newer than' messages are directed to
 214           standard error.  e.g. `checkman > dups'
 215
 216           If you are confident that the duplicates found are indeed
 217           duplicates, you can back them up and delete them to save space.
 218
 219           At this point, running checkman again may yield further duplicates
 220           that were ignored the first time.
 221
 222         * RUN `catman' with appropriate options to create any/all cat files
 223           that you would like pre-formatted.
 224
 225
 226 Multiple build directories
 227 ==========================
 228
 229 It is possible to build man-db in a directory other than the directory
 230 containing this file (and all of the program sources).  This is particularly
 231 useful if compiling on multiple architectures or testing various
 232 configuration options as only a single copy of the sources is required.
 233
 234 To enable this support, simply change directory to where you would like to
 235 build the package and run the configure program in this directory
 236 *from there*.  Further information about this support can be found in the
 237 generic install document `docs/INSTALL.autoconf'.
 238
 239
 240 Makefile targets and variables
 241 ==============================
 242
 243 The standard GNU Makefile targets: all, install, uninstall, mostlyclean,
 244 clean, distclean, realclean and TAGS are available in every Makefile-
 245 supported directory.  In addition, the master Makefile has the dist target
 246 to create a compressed and tarred distribution file.
 247
 248 During the configuration process, `configure' sets the installation
 249 variables, `prefix' and `exec_prefix'.  These are then used to form other
 250 variables such as `bindir' and `sysconfdir'.  To change any of these or
 251 other standard GNU install variables dynamically, issue the `make' command
 252 with variable expressions as arguments, eg. `make prefix=/usr/local/packages'
 253
 254 N.B. If prefix=/usr (either statically or dynamically), then sysconfdir=/etc
 255 instead of the usual $(prefix)/etc.  To force sysconfdir to be /usr/etc, set
 256 it on the make command line.
 257
 258
 259 Default preprocessors
 260 =====================
 261
 262 man-db uses a manual page directed preprocessor system, that is, each manual
 263 page may request preprocessing by a selection of preprocessors.  Some
 264 systems' manual pages do not come with this information built in.  In such
 265 circumstances, it is advisable to set a default list of preprocessors that
 266 each manual page should be passed through, so that those requiring special
 267 processing are readable.  To achieve this, set DEFAULT_MANROFFSEQ (found in
 268 include/manconfig.h) to the appropriate preprocessor string, after running
 269 configure, but prior to compilation.  This is not necessary for the
 270 following systems whose default preprocessing requirements are known.
 271
 272   Known not to require DEFAULT_MANROFFSEQ:
 273     Linux, SunOS
 274   Known to require #define DEFAULT_MANROFFSEQ "t":
 275     Ultrix
 276   Known to require #define DEFAULT_MANROFFSEQ "te":
 277     HP-UX, OSF/1
 278
 279 If unsure of the default preprocessors required by a system, the standard
 280 system's man(1) manual page may provide an answer.
 281
 282
 283 Contacting the maintainer
 284 =========================
 285
 286 The current maintainer of man-db is Colin Watson <cjwatson@debian.org>.
 287 Please feel free to contact me with any queries or problems you may have.
 288 You can report bugs here:
 289
 290   https://savannah.nongnu.org/bugs/?group=man-db