===================================================================
RCS file: /cvs/mandoc/INSTALL,v
retrieving revision 1.1
retrieving revision 1.3.2.1
diff -u -p -r1.1 -r1.3.2.1
--- mandoc/INSTALL 2014/08/08 16:45:39 1.1
+++ mandoc/INSTALL 2014/08/14 20:43:22 1.3.2.1
@@ -1,70 +1,89 @@
-$Id: INSTALL,v 1.1 2014/08/08 16:45:39 schwarze Exp $
+$Id: INSTALL,v 1.3.2.1 2014/08/14 20:43:22 schwarze Exp $
-Installing mdocml, the portable mandoc distribution
----------------------------------------------------
-
+About mdocml, the portable mandoc distribution
+----------------------------------------------
The mandoc manpage compiler toolset is a suite of tools compiling
mdoc(7), the roff(7) macro language of choice for BSD manual pages,
and man(7), the predominant historical language for UNIX manuals.
-For general information, see: http://mdocml.bsd.lv/
+The toolset does not yet implement man(1); that is only scheduled
+for the next release, 1.13.2. It can, however, already serve to
+translate source manpages to the output displayed by man(1).
+For general information, see .
+In this document, we describe the installation and deployment of
+mandoc(1), first as a simple, standalone formatter, and then as part of
+the man(1) system.
+
+In case you have questions or want to provide feedback, read
+. Consider subscribing to the
+discuss@ mailing list mentioned on that page. If you intend to
+help with the development of mandoc, consider subscribing to the
+tech@ mailing list, too.
+
+Enjoy using the mandoc toolset!
+
+Ingo Schwarze, Karlsruhe, August 2014
+
+
+Installation
+------------
Before manually installing mandoc on your system, please check
whether the newest version of mandoc is already installed by default
or available via a binary package or a ports system. A list of the
latest bundled and ported versions of mandoc for various operating
-systems is maintained at: http://mdocml.bsd.lv/ports.html
+systems is maintained at .
-If mandoc is installed, you can check the version by typing: mandoc -V
-The version contained in this distribution tarball is listed near
-the beginning of the file "Makefile". Regarding how packages and
-ports are maintained for your operating system, please consult your
-operating system documentation.
+If mandoc is installed, you can check the version by running "mandoc -V".
+The version contained in this distribution tarball is 1.12.4.
+This is not the newest version available, you can also get 1.13.1.
+Installing 1.12.4 only makes sense if all of the following conditions
+hold for you:
+ - You need apropos(1) and makewhatis(8) functionality.
+ - You do not need the man.cgi(8) web frontend.
+ - You do have the Berkeley database library, version 1.85.
+ - You lack at least one of the following: the SQLite3 database
+ library and/or the fts(3) file hierarchy traversal functions.
+
+Regarding how packages and ports are maintained for your operating
+system, please consult your operating system documentation.
To install mandoc manually, the following steps are needed:
-1. Decide whether you want to build just the basic tools mandoc(1),
-preconv(1) and demandoc(1) or whether you also want to build the
-database tools apropos(1) and makewhatis(8). For the latter, a
-working installation of SQLite is required, see: http://sqlite.org/
-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.
-The database tools also require 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.
+1. Decide whether you want to build the base tools mandoc(1),
+preconv(1) and demandoc(1) only or whether you also want to build the
+database tools apropos(1) and makewhatis(8). For the latter,
+the Berkeley database system, version 1.85, is required.
+It is installed by default on BSD systems and available as an
+optional software package on other systems.
-2. If you choose to build the database tools, too, decide whether
-you also want to build the CGI program, man.cgi(8).
-
-3. Read the beginning of the file "Makefile" from "USER SETTINGS"
+2. Read the beginning of the file "Makefile" from "USER SETTINGS"
to "END OF USER SETTINGS" and edit it as required. In particular,
disable "BUILD_TARGETS += db-build" if you do not want database
-support or enable "BUILD_TARGETS += cgi-build" if you do want
-the CGI program.
+support.
-4. Run the command "make". No separate "./configure" or "make
-depend" steps are needed. The former is run automatically by "make".
-The latter is a maintainer target. If you merely want to build the
-released version as opposed to doing active development, there is
-no need to regenerate the dependency specifications. Any
-POSIX-compatible make, in particular both BSD make and GNU make,
-is supposed to work.
+3. Run "make". No separate "./configure" or "make depend" steps
+are needed. The former is run automatically by "make". The latter
+is a maintainer target. If you merely want to build the released
+version as opposed to doing active development, there is no need
+to regenerate the dependency specifications. Any POSIX-compatible
+make, in particular both BSD make and GNU make, should work.
-5. Run the command "make -n install" and check whether everything
-will be installed to the intended places. Otherwise, edit the *DIR
-variables in the Makefile until it is.
+4. Run "make -n install" and check whether everything will be
+installed to the intended places. Otherwise, edit the *DIR variables
+in the Makefile until it is.
-6. Run "sudo make install". Instead, if you intend to build a binary
+5. 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. To use mandoc(1) as your man(1) formatter, read the "Deployment"
+section below.
+
+Checking autoconfiguration quality
+----------------------------------
If you want to check whether automatic configuration works well
on your platform, consider the following:
@@ -108,12 +127,44 @@ check that no expected "#define HAVE_*" lines are miss
list of tests run can be found in the file "configure".
-In case you have questions or want to provide feedback, look at:
-http://mdocml.bsd.lv/contact.html
+Deployment
+----------
+If you want to integrate the mandoc(1) tools with your existing
+man(1) system as a formatter, then contact us first: on systems without
+mandoc(1) as the default, you may have your work cut out for you!
+Usually, you can have your default installation and mandoc(1) work right
+alongside each other by using user-specific versions of the files
+mentioned below.
-Consider subscribing to the discuss@ mailing list mentioned on that
-page. If you intend to help with the development of mandoc, consider
-subscribing to the tech@ mailing list, too.
+0. Back up each file you want to change!
-Enjoy using the mandoc toolset!
-Ingo Schwarze, Karlsruhe, August 2014
+1. First see whether your system has "/etc/man.conf" or "/etc/manpath.conf"
+(if it has neither, but man(1) is functional, then let us know) or,
+if running as your own user, a per-user override file. In either
+case, find where man(1) is executing nroff(1) or groff(1) to format
+manuals. Replace these calls with mandoc(1).
+
+2. Then make sure that man(1) isn't running preprocessors, so you may
+need to replace tbl(1), eqn(1), and similar references with cat(1).
+Some man(1) implementations, like that on Mac OSX, let you run "man -d"
+to see how the formatter is invoked. Use this to test your changes. On
+Mac OS X, for instance, man(1) will prepend all files with ".ll" and
+".nr" to set the terminal size, so you need to pass "tail -n+2 |
+mandoc(1)" to disregard them.
+
+3. Finally, make sure that mandoc(1) is actually being invoked instead
+of cached pages being pulled up. You can usually do this by commenting
+out NOCACHE or similar.
+
+mandoc(1) still has a long way to go in understanding non-trivial
+low-level roff(7) markup embedded in some man(7) pages. On the BSD
+systems using mandoc(1), third-party software is generally vetted
+on whether it may be formatted with mandoc(1). If not, groff(1)
+is pulled in as a dependency and used to install a pre-formatted
+"catpage" intead of directly as manual page source.
+
+For more background on switching operating systems to use mandoc(1)
+instead of groff(1) to format manuals, see the two BSDCan presentations
+by Ingo Schwarze:
+
+