summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 15:19:27 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 15:19:27 +0000
commite0023883c6d2e6745a19e4b48e186ed156c1fca8 (patch)
tree1a48b8056ec984385d0d862b683535d04d6ed215 /README.md
parentInitial commit. (diff)
downloadman-db-e0023883c6d2e6745a19e4b48e186ed156c1fca8.tar.xz
man-db-e0023883c6d2e6745a19e4b48e186ed156c1fca8.zip
Adding upstream version 2.11.2.upstream/2.11.2upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'README.md')
-rw-r--r--README.md316
1 files changed, 316 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3ee5063
--- /dev/null
+++ b/README.md
@@ -0,0 +1,316 @@
+# The man-db manual pager suite
+
+ https://gitlab.com/man-db/man-db
+
+ https://man-db.gitlab.io/man-db/
+
+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.md 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 C99 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-to-cat filename translation. As such, the following are defined in
+`./include/manconfig.h`:
+
+```c
+#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:
+
+```c
+#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.
+
+* `--disable-manual`
+
+ Don't build or install the man-db manual. This may be useful when
+ cross-compiling, or to reduce the installation size.
+
+
+## Installation
+
+Configure man-db:
+
+* **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 the default section list and other
+ specific definitions.
+
+* `lib/compression.c` 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.
+
+Build man-db:
+
+* **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.
+You can report bugs here:
+
+ https://gitlab.com/man-db/man-db/-/issues
+
+Bugs from before the migration to GitLab may be found here:
+
+ https://savannah.nongnu.org/bugs/?group=man-db