-$Id: INSTALL,v 1.5 2014/08/18 13:27:47 kristaps Exp $
-
-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.
-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 <http://mdocml.bsd.lv/>.
-
-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.
+$Id: INSTALL,v 1.24 2021/09/20 13:25:42 schwarze Exp $
+
+About the portable mandoc distribution
+--------------------------------------
+The mandoc manpage compiler toolset (formerly called "mdocml")
+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.
+
+It includes a man(1) manual viewer and additional tools.
+For general information, see <http://mandoc.bsd.lv/>.
In case you have questions or want to provide feedback, read
-<http://mdocml.bsd.lv/contact.html>. Consider subscribing to the
+<http://mandoc.bsd.lv/contact.html>. 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
+Ingo Schwarze, Karlsruhe, September 2021
Installation
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>.
-
-If mandoc is installed, you can check the version by running "mandoc -V".
-You can find the version contained in this distribution tarball
-by running "./configure".
+systems is maintained at <http://mandoc.bsd.lv/ports.html>.
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. 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 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
a file "configure.local", and re-run "./configure" until the
result seems right to you.
-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
-installed to the intended places. Otherwise, put some *DIR variables
-into "configure.local" and go back to step 2.
-
-5. Run "sudo make install". If you intend to build a binary
+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 4.
+
+7. Optionally run the regression suite.
+Basically, that amounts to "make regress" to do a standard regression
+run, running all tests. For more fine-grained control,
+read "./mandoc -l regress/regress.pl.1",
+then run "cd regress && ./regress.pl" with optional arguments.
+The regression suite requires a reasonably modern Perl interpreter.
+Examples of systems that are too old to run the regression suite
+include Solaris 9, Solaris 10, and Mac OS X 10.4 Tiger.
+On Solaris 11, the suite does run, but some tests fail;
+look at the BUGS section of that manual page.
+
+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. To set up a man.cgi(8) server, read its manual page.
+9. Run the command "sudo makewhatis" to build mandoc.db(5) databases
+in all the directory trees configured in step 3. Whenever installing
+new manual pages, re-run makewhatis(8) to update the databases, or
+apropos(1) will not find the new pages.
-7. To use mandoc(1) as your man(1) formatter, read the "Deployment"
-section below.
+10. To set up a man.cgi(8) server, read its manual page.
+
+Note that a very small number of man(7) pages 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 with mandoc. If not, groff(1) is pulled in as a
+dependency and used to install pre-formatted "catpages" instead of
+manual page sources. This mechanism is used much less frequently
+than in the past. On OpenBSD, only 25 out of about 10000 ports
+still require formatting with groff(1).
Understanding mandoc dependencies
---------------------------------
-The mandoc(1), preconv(1), and demandoc(1) utilities have no external
-dependencies. However, makewhatis(8) and apropos(1) depend on the
-following software:
-
-1. The SQLite database system, 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. Versions
-older than 3.7.5 may or may not work, they have not been tested.
-
-1.2. The fts(3) directory traversion functions.
+The following libraries are required:
+
+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 <https://sourceware.org/bugzilla/show_bug.cgi?id=15838>.
+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 <https://sourceware.org/bugzilla/show_bug.cgi?id=11460>.
+That was presumably fixed in glibc-2.23.
If you run into that problem, set "HAVE_FTS=0" in configure.local.
-1.3. Marc Espie's ohash(3) library.
+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
----------------------------------
or libraries are installed in unusual places or interfaces defined
in unusual headers. You can also look at the file "config.h" and
check that no "#define HAVE_*" differ from your expectations.
-
-
-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.
-
-0. Back up each file you want to change!
-
-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:
-<http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html>
-<http://www.openbsd.org/papers/bsdcan14-mandoc.pdf>
git.ckatri.com / mandoc.git / blobdiff