[BACK]Return to INSTALL CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/INSTALL, Revision 1.2

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

CVSweb