Annotation of mandoc/INSTALL, Revision 1.5
1.5 ! kristaps 1: $Id: INSTALL,v 1.4 2014/08/16 19:00:01 schwarze Exp $
1.1 schwarze 2:
1.2 schwarze 3: About mdocml, the portable mandoc distribution
4: ----------------------------------------------
1.1 schwarze 5: The mandoc manpage compiler toolset is a suite of tools compiling
6: mdoc(7), the roff(7) macro language of choice for BSD manual pages,
7: and man(7), the predominant historical language for UNIX manuals.
1.2 schwarze 8: The toolset does not yet implement man(1); that is only scheduled
9: for the next release, 1.13.2. It can, however, already serve to
10: translate source manpages to the output displayed by man(1).
11: For general information, see <http://mdocml.bsd.lv/>.
12:
13: In this document, we describe the installation and deployment of
14: mandoc(1), first as a simple, standalone formatter, and then as part of
15: the man(1) system.
16:
17: In case you have questions or want to provide feedback, read
18: <http://mdocml.bsd.lv/contact.html>. Consider subscribing to the
19: discuss@ mailing list mentioned on that page. If you intend to
20: help with the development of mandoc, consider subscribing to the
21: tech@ mailing list, too.
22:
23: Enjoy using the mandoc toolset!
24:
25: Ingo Schwarze, Karlsruhe, August 2014
26:
1.1 schwarze 27:
1.2 schwarze 28: Installation
29: ------------
1.1 schwarze 30: Before manually installing mandoc on your system, please check
31: whether the newest version of mandoc is already installed by default
32: or available via a binary package or a ports system. A list of the
33: latest bundled and ported versions of mandoc for various operating
1.2 schwarze 34: systems is maintained at <http://mdocml.bsd.lv/ports.html>.
1.1 schwarze 35:
1.2 schwarze 36: If mandoc is installed, you can check the version by running "mandoc -V".
1.4 schwarze 37: You can find the version contained in this distribution tarball
38: by running "./configure".
1.1 schwarze 39:
1.2 schwarze 40: Regarding how packages and ports are maintained for your operating
41: system, please consult your operating system documentation.
42: To install mandoc manually, the following steps are needed:
1.1 schwarze 43:
1.4 schwarze 44: 1. If you want to build the CGI program, man.cgi(8), too, run the
1.5 ! kristaps 45: command "echo BUILD_CGI=1 > configure.local". Then run "cp
! 46: cgi.h.examples cgi.h" and edit cgi.h as desired.
1.1 schwarze 47:
1.4 schwarze 48: 2. Run "./configure".
49: This script attempts autoconfiguration of mandoc for your system.
50: Read both its standard output and the file "Makefile.local" it
51: generates. If anything looks wrong or different from what you
52: wish, read the file "configure.local.example", create and edit
53: a file "configure.local", and re-run "./configure" until the
54: result seems right to you.
55:
56: 3. Run "make".
57: Any POSIX-compatible make, in particular both BSD make and GNU make,
58: should work. If the build fails, look at "configure.local.example"
59: and go back to step 2.
60:
61: 4. Run "make -n install" and check whether everything will be
62: installed to the intended places. Otherwise, put some *DIR variables
63: into "configure.local" and go back to step 2.
64:
65: 5. Run "sudo make install". If you intend to build a binary
66: package using some kind of fake root mechanism, you may need a
67: command like "make DESTDIR=... install". Read the *-install targets
68: in the "Makefile" to understand how DESTDIR is used.
69:
70: 6. To set up a man.cgi(8) server, read its manual page.
71:
72: 7. To use mandoc(1) as your man(1) formatter, read the "Deployment"
73: section below.
74:
75:
76: Understanding mandoc dependencies
77: ---------------------------------
78: The mandoc(1), preconv(1), and demandoc(1) utilities have no external
79: dependencies. However, makewhatis(8) and apropos(1) depend on the
80: following software:
81:
82: 1. The SQLite database system, see <http://sqlite.org/>.
1.1 schwarze 83: The recommended version of SQLite is 3.8.4.3 or newer. The mandoc
84: toolset is known to work with version 3.7.5 or newer. Versions
85: older than 3.8.3 may not achieve full performance due to the
86: missing SQLITE_DETERMINISTIC optimization flag. Versions older
87: than 3.8.0 may not show full error information if opening a database
88: fails due to the missing sqlite3_errstr() API. Both are very minor
1.2 schwarze 89: problems, apropos(1) is fully usable with SQLite 3.7.5. Versions
90: older than 3.7.5 may or may not work, they have not been tested.
91:
92: 1.2. The fts(3) directory traversion functions.
1.3 schwarze 93: If your system does not have them, the bundled compatibility version
94: will be used, so you need not worry in that case. But be careful: the
1.2 schwarze 95: glibc version of fts(3) is known to be broken on 32bit platforms,
96: see <https://sourceware.org/bugzilla/show_bug.cgi?id=15838>.
1.4 schwarze 97: If you run into that problem, set "HAVE_FTS=0" in configure.local.
1.2 schwarze 98:
99: 1.3. Marc Espie's ohash(3) library.
100: If your system does not have it, the bundled compatibility version
1.1 schwarze 101: will be used, so you probably need not worry about it.
102:
103:
1.2 schwarze 104: Checking autoconfiguration quality
105: ----------------------------------
1.1 schwarze 106: If you want to check whether automatic configuration works well
107: on your platform, consider the following:
108:
109: The mandoc package intentionally does not use GNU autoconf because
110: we consider that toolset a blatant example of overengineering that
111: is obsolete nowadays, since all modern operating systems are now
112: reasonably close to POSIX and do not need arcane shell magic any
113: longer. If your system does need such magic, consider upgrading
114: to reasonably modern POSIX-compliant tools rather than asking for
115: autoconf-style workarounds.
116:
117: As far as mandoc is using any features not mandated by ANSI X3.159-1989
118: ("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems
119: do not have, we intend to provide autoconfiguration tests and
120: compat_*.c implementations. Please report any that turn out to be
121: missing. Note that while we do strive to produce portable code,
122: we do not slavishly restrict ourselves to POSIX-only interfaces.
123: For improved security and readability, we do use well-designed,
124: modern interfaces like reallocarray(3) even if they are still rather
125: uncommon, of course bundling compat_*.c implementations as needed.
126:
127: Where mandoc is using ANSI C or POSIX features that some systems
128: still lack and that compat_*.c implementations can be provided for
129: without too much hassle, we will consider adding them, too, so
130: please report whatever is missing on your platform.
131:
132: The following steps can be used to manually check the automatic
133: configuration on your platform:
134:
1.4 schwarze 135: 1. Run "make distclean".
1.1 schwarze 136:
1.4 schwarze 137: 2. Run "./configure"
1.1 schwarze 138:
139: 3. Read the file "config.log". It shows the compiler commands used
140: to test the libraries installed on your system and the standard
141: output and standard error output these commands produce. Watch out
142: for unexpected failures. Those are most likely to happen if headers
143: or libraries are installed in unusual places or interfaces defined
144: in unusual headers. You can also look at the file "config.h" and
1.4 schwarze 145: check that no "#define HAVE_*" differ from your expectations.
1.1 schwarze 146:
147:
1.2 schwarze 148: Deployment
149: ----------
150: If you want to integrate the mandoc(1) tools with your existing
151: man(1) system as a formatter, then contact us first: on systems without
152: mandoc(1) as the default, you may have your work cut out for you!
153: Usually, you can have your default installation and mandoc(1) work right
154: alongside each other by using user-specific versions of the files
155: mentioned below.
156:
157: 0. Back up each file you want to change!
158:
159: 1. First see whether your system has "/etc/man.conf" or "/etc/manpath.conf"
160: (if it has neither, but man(1) is functional, then let us know) or,
161: if running as your own user, a per-user override file. In either
162: case, find where man(1) is executing nroff(1) or groff(1) to format
163: manuals. Replace these calls with mandoc(1).
164:
165: 2. Then make sure that man(1) isn't running preprocessors, so you may
166: need to replace tbl(1), eqn(1), and similar references with cat(1).
167: Some man(1) implementations, like that on Mac OSX, let you run "man -d"
168: to see how the formatter is invoked. Use this to test your changes. On
169: Mac OS X, for instance, man(1) will prepend all files with ".ll" and
170: ".nr" to set the terminal size, so you need to pass "tail -n+2 |
171: mandoc(1)" to disregard them.
172:
173: 3. Finally, make sure that mandoc(1) is actually being invoked instead
174: of cached pages being pulled up. You can usually do this by commenting
175: out NOCACHE or similar.
176:
177: mandoc(1) still has a long way to go in understanding non-trivial
178: low-level roff(7) markup embedded in some man(7) pages. On the BSD
179: systems using mandoc(1), third-party software is generally vetted
180: on whether it may be formatted with mandoc(1). If not, groff(1)
181: is pulled in as a dependency and used to install a pre-formatted
182: "catpage" intead of directly as manual page source.
183:
184: For more background on switching operating systems to use mandoc(1)
185: instead of groff(1) to format manuals, see the two BSDCan presentations
186: by Ingo Schwarze:
187: <http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html>
188: <http://www.openbsd.org/papers/bsdcan14-mandoc.pdf>
CVSweb