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(7) pages whilst providing token support for man(7).

What are UNIX manuals? Read manuals(7) for an introduction.

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 are the man(3) and mdoc(3) libraries, validating compilers producing intermediate-form output from -man or -mdoc input. 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(1), which formats manuals for display on the terminal. Its purpose is to deprecate usage of groff for displaying -mdoc and, to a limited extent, -man manuals on the terminal.

Please submit patches, bug reports and suggestions! Although a significant implementation exists, work remains for the backend library and especially the front-end utilities. See the contact information below for submissions.

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 may be found in the /snapshots/ directory.

% cd /tmp
% ftp -V -o- http://mdocml.bsd.lv/snapshots/mdocml.tar.gz | tar -zvxf -
% cd mdocml
% make all
% make regress
# 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

# 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

# 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

# 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

CONTACT

Please contact Kristaps, kris...@kth.se, with questions, bug reports, patches, and so on.

If you'd like to submit patches, please contact us beforehand in case larger changes are pending but not checked in. If making a bug report, please make sure it's repeatable on the most current snapshot.

Copyright © 2008, 2009 Kristaps Džonsons, $Date: 2009/04/05 16:34:22 $