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, libman, and libroff validating compiler libraries. All 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 front-end is mandoc, which formats manuals for display.

The mdocml suite is a BSD.lv Project member.

SOURCES

Sources correctly build and install on DragonFly BSD, FreeBSD, OpenBSD, NetBSD, GNU/Linux, and many other operating systems, tested variously on i386, AMD64, alpha, and others. The most current version is @VERSION@, dated @VDATE@. A full ChangeLog (txt) is written with each release.

Current

Source archive	/snapshots/mdocml.tar.gz (md5)
Online source	cvsweb

Downstream

DragonFly BSD	usr.bin/mandoc
FreeBSD	ports/textproc/mdocml
NetBSD	src/external/bsd/mdocml
OpenBSD	src/usr.bin/mandoc

Historical

Source archive

/snapshots/

DOCUMENTATION

These manuals are generated automatically and refer to the current snapshot.

man(3)	man macro compiler library text \| postscript
man(7)	man language reference text \| postscript
mandoc(1)	format and display UNIX manuals text \| postscript
mandoc_char(7)	mandoc special characters text \| postscript
mdoc(3)	mdoc macro compiler library text \| postscript
mdoc(7)	mdoc language reference text \| postscript
roff(3)	roff macro compiler library text \| postscript
roff(7)	roff-mandoc language reference text \| postscript

See Writing UNIX Manual Pages for a general introduction to manpages and mdoc.

CONTACT

For all issues related to mdocml, contact Kristaps Dzonsons, kris...@bsd.lv.

You may also subscribe to several mailing lists (these require subscription, which is moderated). An archive is not yet available on-line, although you may request one once subscribed.

disc...@mdocml.bsd.lv	high-level discussions and version announcements
tec...@mdocml.bsd.lv	low-level discussions
sou...@mdocml.bsd.lv	source commit messages

NEWS

12-07-2010: version 1.10.4

Lots of features developed during both Summer of Code and the OpenBSD c2k10 hackathon:

minimal ds roff symbols are supported
Bk mdoc support
beautified SYNOPSIS section output
variable font-width and paper-size support in mandoc -Tps output
acceptance of scope-block breakage in mdoc
clarify error message status
many minor bug-fixes and formatting issues resolved

19-06-2010: version 1.10.2

Small release featuring text-decoration in -Tps output, a few minor relaxations of errors, and some optimisations.

07-06-2010: version 1.10.1

This primarily focusses on the Bl and It macros described in mdoc. Multi-line column support is now fully compatible with groff, as are implicit list entries for columns. Removed manuals.7 in favour of http://manpages.bsd.lv. The way we handle the SYNOPSIS section (see the SYNOPSIS documentation in MANUAL STRUCTURE) has also been considerably simplified compared to groff's method. Furthermore, the -Owidth=width output option has been added to -Tascii (see mandoc). Lastly, initial PostScript output has been added with the -Tps option to mandoc. It's brutally simple at the moment: fixed-font, with no font decorations.

29-05-2010: version 1.10.0

Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD. This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10. Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:

a libroff preprocessor in front of libmdoc and libman stripping out roff instructions;
end-of-sentence (EOS) detection in free-form and macro lines;
correct handling of tab-separated columnar lists in -mdoc;
improved main calling routines to optionally use mmap() for better performance;
cleaned up exiting when invoked as -Tlint or over multiple files with -fign-errors;
error and warning message handling re-written to be unified for libroff, libmdoc, and libman;
handling of badly-nested explicit-scoped macros;
improved free-form text parsing in libman and libmdoc;
significant GNU troff compatibility improvements in -Tascii, largely in terms of spacing;
a regression framework for making sure the many fragilities of GNU troff aren't trampled in subsequent work;
support for -Tascii breaking at hyphens encountered in free-form text;
and many more minor fixes and improvements (no really, consult cvsweb and see for yourself!).

13-05-2010: version 1.9.25

Fixed handling of \*(Ba escape. Backed out -fno-ign-chars (pointless complexity). Fixed erroneous breaking of literal lines. Fixed SYNOPSIS breaking lines before non-initial macros. Changed default section ordering. Most importantly, the framework for end-of-sentence double-spacing is in place, now implemented for the end-of-sentence, end-of-line rule. This is a stable roll-back point before the mandoc hackathon in Rostock!

09-05-2010: version 1.9.24

Rolled back break-at-hyphen. -DUGLY is now the default (no feature splits!). Free-form text is not de-chunked any more: lines are passed whole-sale into the front-end, including whitespace. Added mailing lists. Lastly, mdocml is the focus of two Google Summer of Code projects this year: mandoc -Tps (NetBSD) and BSD-licensed Text-Processing Tools (FreeBSD).

See cvsweb for historical notes.