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 troff 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).

mdocml consists of the libmdoc, libman, and libroff validating compilers; and mandoc, which interfaces with the compiler libraries to format output for UNIX terminals, XHTML, HTML, and PostScript. mdocml is a BSD.lv project.

Disambiguation: mdocml is often referred to by its installed binary, mandoc.

SOURCES

mdocml is architecture- and system-neutral, written in plain-old C. 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 | pdf | postscript)
man(7) man language reference (text | pdf | postscript)
mandoc(1) format and display UNIX manuals (text | pdf | postscript)
mandoc_char(7) mandoc special characters (text | pdf | postscript)
mdoc(3) mdoc macro compiler library (text | pdf | postscript)
mdoc(7) mdoc language reference (text | pdf | postscript)
roff(3) roff macro compiler library (text | pdf | postscript)
roff(7) roff-mandoc language reference (text | pdf | postscript)

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

CONTACT

Please use the mailing lists for bug-reports, patches, questions, etc. Beyond that, contact Kristaps at kris...@bsd.lv.

You may also subscribe to several mailing lists (these require subscription, which is moderated).

disc...@mdocml.bsd.lv bug-reports, general questions, and announcements (archive)
tec...@mdocml.bsd.lv patches and system discussions (archive)
sou...@mdocml.bsd.lv source commit messages (archive)

NEWS

xx-12-2010: version 1.10.8

Significant improvements merged from OpenBSD downstream, including

  • many new roff components,
  • in-line implementation of troff's soelim,
  • broken-block handling,
  • overhauled error classifications, and
  • cleaned up handling of error conditions.

Also overhauled the -Thtml and -Txhtml output modes. It now displays similarly in arbitrary browsers, including lynx! Internally, libmdoc and libman have been cleaned up and reduced in size and complexity.

27-09-2010: version 1.10.6

Calling conventions for mandoc have changed: -W improved and -f deprecated. Non-ASCII characters are also now uniformly discarded. Lots of documentation improvements. Many incremental fixes accomodating for groff's more interesting productions. Lastly, pod2man preambles are now fully accepted after some considerable roff and special character support.

27-07-2010: version 1.10.5

Primarily a bug-fix and polish release, but including -Tpdf support in mandoc by way of Summer of Code. Highlights:

  • fix Sm and Bd handling
  • fix end-of-sentence handling for embedded sentences
  • polish man documentation
  • document all mdoc macros
  • polish mandoc -Tps output
  • lots of internal clean-ups in character escapes
  • un-break literal contexts in man documents
  • improve -Thtml output for -man
  • add mandoc -Tpdf support

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!).

See cvsweb for historical notes.

Copyright © 2008–2010 Kristaps Dzonsons, $Date$