===================================================================
RCS file: /cvs/mandoc/INSTALL,v
retrieving revision 1.12
retrieving revision 1.18
diff -u -p -r1.12 -r1.18
--- mandoc/INSTALL 2015/07/19 06:05:16 1.12
+++ mandoc/INSTALL 2017/02/08 12:24:10 1.18
@@ -1,4 +1,4 @@
-$Id: INSTALL,v 1.12 2015/07/19 06:05:16 schwarze Exp $
+$Id: INSTALL,v 1.18 2017/02/08 12:24:10 schwarze Exp $
About mdocml, the portable mandoc distribution
----------------------------------------------
@@ -16,7 +16,7 @@ tech@ mailing list, too.
Enjoy using the mandoc toolset!
-Ingo Schwarze, Karlsruhe, March 2015
+Ingo Schwarze, Karlsruhe, February 2017
Installation
@@ -31,11 +31,21 @@ Regarding how packages and ports are maintained for yo
system, please consult your operating system documentation.
To install mandoc manually, the following steps are needed:
-1. If you want to build the CGI program, man.cgi(8), too, run the
-command "echo BUILD_CGI=1 > configure.local". Then run "cp
-cgi.h.examples cgi.h" and edit cgi.h as desired.
+1. If you want to build the CGI program, man.cgi(8), too,
+run the command "echo BUILD_CGI=1 >> configure.local".
+Then run "cp cgi.h.example cgi.h" and edit cgi.h as desired.
-2. Run "./configure".
+2. If you also want to build the new catman(8) utility, run the
+command "echo BUILD_CATMAN=1 >> configure.local". Note that it
+is unlikely to be a drop-in replacement providing the same
+functionality as your system's "catman", if your operating
+system contains one.
+
+3. Define MANPATH_DEFAULT in configure.local
+if /usr/share/man:/usr/X11R6/man:/usr/local/man is not appropriate
+for your operating system.
+
+4. Run "./configure".
This script attempts autoconfiguration of mandoc for your system.
Read both its standard output and the file "Makefile.local" it
generates. If anything looks wrong or different from what you
@@ -45,35 +55,32 @@ result seems right to you.
On Solaris 10 and earlier, you may have to run "ksh ./configure"
because the native /bin/sh lacks some POSIX features.
-3. Run "make".
+5. Run "make".
Any POSIX-compatible make, in particular both BSD make and GNU make,
should work. If the build fails, look at "configure.local.example"
and go back to step 2.
-4. Run "make -n install" and check whether everything will be
+6. Run "make -n install" and check whether everything will be
installed to the intended places. Otherwise, put some *DIR or *NM*
-variables into "configure.local" and go back to step 2.
+variables into "configure.local" and go back to step 4.
-5. Run "sudo make install". If you intend to build a binary
+7. Optionally run the regression suite.
+Basically, that amounts to "cd regress && ./regress.pl".
+But you should probably look at "./mandoc -l regress/regress.pl.1"
+first.
+
+8. Run "sudo make install". If you intend to build a binary
package using some kind of fake root mechanism, you may need a
command like "make DESTDIR=... install". Read the *-install targets
in the "Makefile" to understand how DESTDIR is used.
-6. If you want to use the integrated man(1) and your system uses
-manpath(1), make sure it is configured correctly, in particular,
-it returns all directory trees where manual pages are installed.
-Otherwise, if your system uses man.conf(5), make sure it contains
-a "_whatdb" line for each directory tree, and the order of these
-lines meets your wishes.
+9. Run the command "sudo makewhatis" to build mandoc.db(5) databases
+in all the directory trees configured in step 6. Whenever installing
+new manual pages, re-run makewhatis(8) to update the databases, or
+apropos(1) will not find the new pages.
-7. If you compiled with database support, run the command "sudo
-makewhatis" to build mandoc.db(5) databases in all the directory
-trees configured in step 6. Whenever installing new manual pages,
-re-run makewhatis(8) to update the databases, or apropos(1) will
-not find the new pages.
+10. To set up a man.cgi(8) server, read its manual page.
-8. To set up a man.cgi(8) server, read its manual page.
-
Note that some man(7) pages may contain low-level roff(7) markup
that mandoc does not yet understand. On some BSD systems using
mandoc, third-party software is vetted on whether it may be formatted
@@ -84,31 +91,26 @@ manual page source.
Understanding mandoc dependencies
---------------------------------
-The mandoc(1), man(1), and demandoc(1) utilities only depend
-on the zlib library for decompressing gzipped manual pages,
-but makewhatis(8) and apropos(1) depend on the following
-additional software:
+The following libraries are required:
-1. The SQLite database system, see .
-The recommended version of SQLite is 3.8.4.3 or newer. The mandoc
-toolset is known to work with version 3.7.5 or newer. Versions
-older than 3.8.3 may not achieve full performance due to the
-missing SQLITE_DETERMINISTIC optimization flag. Versions older
-than 3.8.0 may not show full error information if opening a database
-fails due to the missing sqlite3_errstr() API. Both are very minor
-problems, apropos(1) is fully usable with SQLite 3.7.5. Versions
-older than 3.7.5 may or may not work, they have not been tested.
+1. zlib for decompressing gzipped manual pages.
2. The fts(3) directory traversion functions.
If your system does not have them, the bundled compatibility version
-will be used, so you need not worry in that case. But be careful: the
-glibc version of fts(3) is known to be broken on 32bit platforms,
-see .
+will be used, so you need not worry in that case. But be careful: old
+glibc versions of fts(3) were known to be broken on 32bit platforms,
+see .
+That was presumably fixed in glibc-2.23.
If you run into that problem, set "HAVE_FTS=0" in configure.local.
3. Marc Espie's ohash(3) library.
If your system does not have it, the bundled compatibility version
will be used, so you probably need not worry about it.
+
+One of the chief design goals of the mandoc toolbox is to make
+sure that nothing related to documentation requires C++.
+Consequently, linking mandoc against any kind of C++ program
+would defeat the purpose and is not supported.
Checking autoconfiguration quality