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