DESCRIPTION

mdocml is a suite of tools compiling “mdoc”, the roff macro package for BSD manual pages. The mission of mdocml is to deprecate groff, the GNU roff implementation, for displaying BSD mdoc pages.

Why? groff amounts to roughly 5,2 MB of source code (OpenBSD 4.2), some 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 the libmdoc library, a validating scanner-parser producing intermediate-form output from mdoc input. libmdoc is a simple, fast library operating on memory buffers of mdoc input. Its intermediate output, an abstract syntax tree, is fully documented in the mdoc(3) reference manual.

There are three utilities implementing mdoc(3):

• mdocterm(1) – formats mdoc input for display on the terminal
• mdochtml(1) – formats mdoc input as HTML/CSS (nascent)
• mdoclint(1) – validates mdoc input
• mdoctree(1) – prints input abstract syntax tree

The mdocterm(1) utility is intended to deprecate usage of groff for displaying BSD manuals to the terminal, either directly or cached as a “catman” page.

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

INSTALLING SOURCES

Sources correctly build and install on OpenBSD, NetBSD and Linux operating systems, tested variously on i386, AMD64 and Alpha.

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 port and NetBSD pkgsrc forms at /ports-openbsd/ and /ports-netbsd/, respectively. Please read the OpenBSD Ports FAQ or NetBSD pkgsrc guide, first.

OpenBSD port

# pkg_delete mdocml
# cd /usr/ports/devel/
# 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/devel/
# rm -rf mdocml
# ftp -V -o- http://mdocml.bsd.lv/ports-netbsd/mdocml.tar.gz | tar -zvxf -
# cd mdocml
# make build
# 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.