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.

The mdocml utility is a BSD.lv Project member.

SOURCES

Sources correctly build and install on DragonFly BSD, FreeBSD, OpenBSD, NetBSD, and GNU/Linux 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.

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

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.

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

xx-05-2010	Day 1 of Rostock hackathon: proper handling of quotations in tab-separated column lists, finished patching of SYNOPSIS breaking (1.9.25), fixed pre-comment white-space stripping, added end-of-sentence spacing to black partial-implicit macros, relaxed column warnings, relaxed acceptence of bad standards arguments, significant documentation of lists in mdoc(7). Version: 1.9.26.
13-05-2010	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! Version: 1.9.25.
09-05-2010	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). Version: 1.9.24.
07-04-2010	mdocml has been linked to the OpenBSD build. This version incorporates many small changes, mostly from patches by OpenBSD, allowing crufty manuals to slip by with warnings instead of erroring-out. Some subtle semantic issues, such as punctuation scope, have also been fixed. Lastly, some issues with -Thtml have been fixed, which prompted an update to the online manual pages style layout. Version: 1.9.23.
31-03-2010	Version 1.9.22: adjusted merge of the significant work by Ingo Schwarze in getting Xo blocks (block full implicit, e.g., It for non-columnar lists) to work properly. This isn't enabled by default: you must specify -DUGLY as a compiler flag (see the Makefile for details).
30-03-2010	Version 1.9.20: more efforts to get roff instructions in -man documents under control. Note that roff instructions embedded in line-scoped, next-line macros (e.g. B) are not supported. Leading punctuation for -mdoc macros, such as Fl ( ( a, are now correctly handled.
27-03-2010	Version 1.9.18: many fixes (largely pertaining to scope) and improvements (e.g., handling of apostrophe-control macros, which fixes the strange BR seen in some macro output) to handling roff instructions in -man documents.
25-03-2010	Version 1.9.17 highlights: accept perlpod standard preamble. Also accept (and discard) de, dei, am, ami, and ig roff macro blocks.
22-03-2010	Version 1.9.16 highlights: inspired by patches and bug reports by Ingo Schwarze, allowed -man to accept non-printing elements to be nested within next-line scopes, such as br within B or TH, which is valid roff. Longsoon architecture also noted and Makefile cleaned up.
18-02-2010	Moved to our new BSD.lv home. Version 1.9.15 highlights: XHTML is now an acceptable output mode for mandoc(1); Xr made more compatible with groff; Vt fixed when invoked in SYNOPSIS; \\ escape removed; end-of-line white-space detected for all lines; subtle bug fixed in list display for some modes; compatibility layer checked in for compilation in diverse UNIX systems; and column lengths handled correctly.