mdocml – mdoc macro compiler

DESCRIPTION

mdocml is a suite of tools compiling “-mdoc”, the roff macro package of choice for BSD manual pages, and “-man”, the predominant historical package for UNIX manuals. The mission of mdocml is to deprecate groff, the GNU roff implementation, for displaying -mdoc pages whilst providing token support for -man.

Why? groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL. It runs slowly, produces uncertain output, and varies in operation from system to system. mdocml strives to fix this (respectively small, C, ISC-licensed, fast and regular).

The core of mdocml is composed of the libmdoc and libman validating compiler libraries. Both are simple, fast libraries operating on memory buffers, so they may be used for a variety of front-ends (terminal-based, CGI and so on). The primary front-end is mandoc, which formats manuals for display on the terminal.

INSTALLING SOURCES

Sources correctly build and install on FreeBSD, OpenBSD, NetBSD and Linux operating systems, tested variously on i386, AMD64, alpha and others. The most current version is @VERSION@, dated @VDATE@.

Snapshot source

CVS sources are checkedout and snapshotted with version updates. These (and all historical snapshots) may be found in the /snapshots/ directory. A full ChangeLog is written with each new snapshot.

% cd /tmp
% ftp -V -o- http://mdocml.bsd.lv/snapshots/mdocml.tar.gz | tar -zvxf -
% cd mdocml
% make all
# make install

Snapshot port/pkgsrc

The source snapshot is automatically converted into OpenBSD, NetBSD and FreeBSD ports at /ports-openbsd/, /ports-netbsd/ and /ports-freebsd/, respectively. Please read the OpenBSD Ports FAQ, the NetBSD pkgsrc guide or the FreeBSD ports guide, first.

OpenBSD port

Note: the mdocml utility is part of OpenBSD's base system at usr.bin/mandoc. Please use this instead of the provided port.

# pkg_delete mdocml
# cd /usr/ports/textproc/
# rm -rf mdocml
# ftp -V -o- http://mdocml.bsd.lv/ports-openbsd/mdocml.tar.gz | tar -zvxf -
# cd mdocml
# make build
# make install

NetBSD pkgsrc

Note: a pkgsrc port is maintained in-tree at textproc/mdocml. Please use this instead of the provided pkgsrc.

# pkg_delete mdocml
# cd /usr/pkgsrc/textproc/
# rm -rf mdocml
# ftp -V -o- http://mdocml.bsd.lv/ports-netbsd/mdocml.tar.gz | tar -zvxf -
# cd mdocml
# make build
# make install

FreeBSD port

Note: a port is maintained in-tree at textproc/mdocml. Please use this instead of the provided port.

# pkg_delete -x mdocml
# cd /tmp
# ftp -V -o- http://mdocml.bsd.lv/ports-freebsd/mdocml.tar.gz | tar -zvxf -
# cd mdocml
# make
# make install

DOCUMENTATION

mandoc(1) format and display UNIX manuals
mandoc_char(7) mandoc special characters
mdoc(7) mdoc language reference
man(7) man language reference
manuals(7) a guide to writing UNIX manuals
mdoc(3) mdoc macro compiler library
man(3) man macro compiler library

CONTACT

For all issues related to mdocml, contact Kristaps, kris...@kth.se.

If you want to receive a semi-automated mail-out of new versions, then please write with a message subject of “subscribe mdocml” (or, symmetrically, “unsubscribe mdocml”).

We don't offer anonymous CVS access. If you must have read-only access to the CVS tree (for down-stream maintenance and so on), then please contact Kristaps directly for a read-only CVS account. We strongly suggest using snapshots, instead.

Copyright © 2008, 2009 Kristaps Džonsons, $Date$