Annotation of mandoc/INSTALL, Revision 1.3.2.1
1.3.2.1 ! schwarze 1: $Id: INSTALL,v 1.3 2014/08/11 01:39:00 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.3.2.1 ! schwarze 37:
! 38: The version contained in this distribution tarball is 1.12.4.
! 39: This is not the newest version available, you can also get 1.13.1.
! 40: Installing 1.12.4 only makes sense if all of the following conditions
! 41: hold for you:
! 42:
! 43: - You need apropos(1) and makewhatis(8) functionality.
! 44: - You do not need the man.cgi(8) web frontend.
! 45: - You do have the Berkeley database library, version 1.85.
! 46: - You lack at least one of the following: the SQLite3 database
! 47: library and/or the fts(3) file hierarchy traversal functions.
1.1 schwarze 48:
1.2 schwarze 49: Regarding how packages and ports are maintained for your operating
50: system, please consult your operating system documentation.
51: To install mandoc manually, the following steps are needed:
1.1 schwarze 52:
1.2 schwarze 53: 1. Decide whether you want to build the base tools mandoc(1),
54: preconv(1) and demandoc(1) only or whether you also want to build the
55: database tools apropos(1) and makewhatis(8). For the latter,
1.3.2.1 ! schwarze 56: the Berkeley database system, version 1.85, is required.
! 57: It is installed by default on BSD systems and available as an
! 58: optional software package on other systems.
1.1 schwarze 59:
1.3.2.1 ! schwarze 60: 2. Read the beginning of the file "Makefile" from "USER SETTINGS"
1.1 schwarze 61: to "END OF USER SETTINGS" and edit it as required. In particular,
62: disable "BUILD_TARGETS += db-build" if you do not want database
1.3.2.1 ! schwarze 63: support.
1.1 schwarze 64:
1.3.2.1 ! schwarze 65: 3. Run "make". No separate "./configure" or "make depend" steps
1.2 schwarze 66: are needed. The former is run automatically by "make". The latter
67: is a maintainer target. If you merely want to build the released
68: version as opposed to doing active development, there is no need
69: to regenerate the dependency specifications. Any POSIX-compatible
70: make, in particular both BSD make and GNU make, should work.
71:
1.3.2.1 ! schwarze 72: 4. Run "make -n install" and check whether everything will be
1.2 schwarze 73: installed to the intended places. Otherwise, edit the *DIR variables
74: in the Makefile until it is.
1.1 schwarze 75:
1.3.2.1 ! schwarze 76: 5. Run "sudo make install". If you intend to build a binary
1.1 schwarze 77: package using some kind of fake root mechanism, you may need a
78: command like "make DESTDIR=... install". Read the *-install targets
79: in the "Makefile" to understand how DESTDIR is used.
80:
1.3.2.1 ! schwarze 81: 6. To use mandoc(1) as your man(1) formatter, read the "Deployment"
1.2 schwarze 82: section below.
83:
1.1 schwarze 84:
1.2 schwarze 85: Checking autoconfiguration quality
86: ----------------------------------
1.1 schwarze 87: If you want to check whether automatic configuration works well
88: on your platform, consider the following:
89:
90: The mandoc package intentionally does not use GNU autoconf because
91: we consider that toolset a blatant example of overengineering that
92: is obsolete nowadays, since all modern operating systems are now
93: reasonably close to POSIX and do not need arcane shell magic any
94: longer. If your system does need such magic, consider upgrading
95: to reasonably modern POSIX-compliant tools rather than asking for
96: autoconf-style workarounds.
97:
98: As far as mandoc is using any features not mandated by ANSI X3.159-1989
99: ("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems
100: do not have, we intend to provide autoconfiguration tests and
101: compat_*.c implementations. Please report any that turn out to be
102: missing. Note that while we do strive to produce portable code,
103: we do not slavishly restrict ourselves to POSIX-only interfaces.
104: For improved security and readability, we do use well-designed,
105: modern interfaces like reallocarray(3) even if they are still rather
106: uncommon, of course bundling compat_*.c implementations as needed.
107:
108: Where mandoc is using ANSI C or POSIX features that some systems
109: still lack and that compat_*.c implementations can be provided for
110: without too much hassle, we will consider adding them, too, so
111: please report whatever is missing on your platform.
112:
113: The following steps can be used to manually check the automatic
114: configuration on your platform:
115:
116: 1. Run "make clean".
117:
118: 2. Run "make config.h"
119:
120: 3. Read the file "config.log". It shows the compiler commands used
121: to test the libraries installed on your system and the standard
122: output and standard error output these commands produce. Watch out
123: for unexpected failures. Those are most likely to happen if headers
124: or libraries are installed in unusual places or interfaces defined
125: in unusual headers. You can also look at the file "config.h" and
126: check that no expected "#define HAVE_*" lines are missing. The
127: list of tests run can be found in the file "configure".
128:
129:
1.2 schwarze 130: Deployment
131: ----------
132: If you want to integrate the mandoc(1) tools with your existing
133: man(1) system as a formatter, then contact us first: on systems without
134: mandoc(1) as the default, you may have your work cut out for you!
135: Usually, you can have your default installation and mandoc(1) work right
136: alongside each other by using user-specific versions of the files
137: mentioned below.
138:
139: 0. Back up each file you want to change!
140:
141: 1. First see whether your system has "/etc/man.conf" or "/etc/manpath.conf"
142: (if it has neither, but man(1) is functional, then let us know) or,
143: if running as your own user, a per-user override file. In either
144: case, find where man(1) is executing nroff(1) or groff(1) to format
145: manuals. Replace these calls with mandoc(1).
146:
147: 2. Then make sure that man(1) isn't running preprocessors, so you may
148: need to replace tbl(1), eqn(1), and similar references with cat(1).
149: Some man(1) implementations, like that on Mac OSX, let you run "man -d"
150: to see how the formatter is invoked. Use this to test your changes. On
151: Mac OS X, for instance, man(1) will prepend all files with ".ll" and
152: ".nr" to set the terminal size, so you need to pass "tail -n+2 |
153: mandoc(1)" to disregard them.
154:
155: 3. Finally, make sure that mandoc(1) is actually being invoked instead
156: of cached pages being pulled up. You can usually do this by commenting
157: out NOCACHE or similar.
158:
159: mandoc(1) still has a long way to go in understanding non-trivial
160: low-level roff(7) markup embedded in some man(7) pages. On the BSD
161: systems using mandoc(1), third-party software is generally vetted
162: on whether it may be formatted with mandoc(1). If not, groff(1)
163: is pulled in as a dependency and used to install a pre-formatted
164: "catpage" intead of directly as manual page source.
165:
166: For more background on switching operating systems to use mandoc(1)
167: instead of groff(1) to format manuals, see the two BSDCan presentations
168: by Ingo Schwarze:
169: <http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html>
170: <http://www.openbsd.org/papers/bsdcan14-mandoc.pdf>
CVSweb