188 lines
8.5 KiB
Plaintext
188 lines
8.5 KiB
Plaintext
$Id: INSTALL,v 1.2 2014/08/10 17:22:26 schwarze 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.
|
|
|
|
In case you have questions or want to provide feedback, read
|
|
<http://mdocml.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
|
|
|
|
|
|
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>.
|
|
|
|
If mandoc is installed, you can check the version by running "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.
|
|
To install mandoc manually, the following steps are needed:
|
|
|
|
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 following dependencies are required:
|
|
|
|
1.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.
|
|
A compatibility version will be bundled for 1.13.2 but is not available
|
|
yet. If you want apropos(1) and makewhatis(8) but do not have fts(3),
|
|
please stay with mandoc 1.12.3 for now and upgrade first to 1.12.4,
|
|
then to 1.13.2 when these versionns are released. 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>.
|
|
|
|
1.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.
|
|
|
|
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"
|
|
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.
|
|
|
|
4. 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 "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". 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.
|
|
|
|
7. To set up a man.cgi(8) server, read its manual page.
|
|
|
|
8. 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:
|
|
|
|
The mandoc package intentionally does not use GNU autoconf because
|
|
we consider that toolset a blatant example of overengineering that
|
|
is obsolete nowadays, since all modern operating systems are now
|
|
reasonably close to POSIX and do not need arcane shell magic any
|
|
longer. If your system does need such magic, consider upgrading
|
|
to reasonably modern POSIX-compliant tools rather than asking for
|
|
autoconf-style workarounds.
|
|
|
|
As far as mandoc is using any features not mandated by ANSI X3.159-1989
|
|
("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems
|
|
do not have, we intend to provide autoconfiguration tests and
|
|
compat_*.c implementations. Please report any that turn out to be
|
|
missing. Note that while we do strive to produce portable code,
|
|
we do not slavishly restrict ourselves to POSIX-only interfaces.
|
|
For improved security and readability, we do use well-designed,
|
|
modern interfaces like reallocarray(3) even if they are still rather
|
|
uncommon, of course bundling compat_*.c implementations as needed.
|
|
|
|
Where mandoc is using ANSI C or POSIX features that some systems
|
|
still lack and that compat_*.c implementations can be provided for
|
|
without too much hassle, we will consider adding them, too, so
|
|
please report whatever is missing on your platform.
|
|
|
|
The following steps can be used to manually check the automatic
|
|
configuration on your platform:
|
|
|
|
1. Run "make clean".
|
|
|
|
2. Run "make config.h"
|
|
|
|
3. Read the file "config.log". It shows the compiler commands used
|
|
to test the libraries installed on your system and the standard
|
|
output and standard error output these commands produce. Watch out
|
|
for unexpected failures. Those are most likely to happen if headers
|
|
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 expected "#define HAVE_*" lines are missing. The
|
|
list of tests run can be found in the file "configure".
|
|
|
|
|
|
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>
|