1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
5 <META NAME="resource-type" CONTENT="document">
6 <LINK REL="stylesheet" HREF="index.css" TYPE="text/css" MEDIA="all">
7 <TITLE>mdocml | mdoc macro compiler</TITLE>
10 <TABLE CLASS="frame" SUMMARY="[frame]">
16 <B>mdocml</B> – mdoc macro compiler
23 <A NAME="description">DESCRIPTION</A>
27 <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <Q>-<A HREF="mdoc.7.html">mdoc</A></Q>, the
28 roff macro package of choice for BSD manual pages, and <Q>-<A HREF="man.7.html">man</A></Q>, the
29 predominant historical package for UNIX manuals. The mission of <SPAN CLASS="nm">mdocml</SPAN> is to
30 deprecate <A HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU troff
31 implementation, for displaying -mdoc pages whilst providing token support for -man.
35 Why? groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL. It runs
36 slowly, produces uncertain output, and varies in operation from system to system. mdocml strives to fix
37 this (respectively small, C, <A CLASS="external"
38 HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
42 <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mdoc.3.html">libmdoc</A>, <A
43 HREF="man.3.html">libman</A>, and <A HREF="roff.3.html">libroff</A> validating compilers; and <A
44 HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler libraries to format output for UNIX
45 terminals, XHTML, HTML, PostScript, and PDF. <SPAN CLASS="nm">mdocml</SPAN> is a <A CLASS="external"
46 HREF="http://bsd.lv/">BSD.lv</A> project.
50 <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary,
58 <A NAME="sources">SOURCES</A>
62 <SPAN CLASS="nm">mdocml</SPAN> is architecture- and system-neutral, written in plain-old C. The most
63 current version is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>. A full
64 <A HREF="ChangeLog.html">ChangeLog</A> (<A HREF="ChangeLog.txt">txt</A>) is written with each release.
71 <TABLE WIDTH="100%" SUMMARY="Current Sources">
76 <TD>Source archive</TD>
78 <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
79 (<A HREF="/snapshots/mdocml.md5">md5</A>)
83 <TD>Online source</TD>
85 <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
95 <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
100 <TD>DragonFly BSD</TD>
102 <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
103 CLASS="external">usr.bin/mandoc</A>
109 <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
110 CLASS="external">ports/textproc/mdocml</A>
116 <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
117 CLASS="external">src/external/bsd/mdocml</A>
123 <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
124 CLASS="external">src/usr.bin/mandoc</A>
134 <TABLE WIDTH="100%" SUMMARY="Archived Sources">
139 <TD>Source archive</TD>
141 <A HREF="/snapshots/">/snapshots/</A>
151 <A NAME="documentation">DOCUMENTATION</A>
155 These manuals are generated automatically and refer to the current snapshot.
158 <TABLE WIDTH="100%" SUMMARY="Documentation">
163 <TD VALIGN="top"><A HREF="man.3.html">man(3)</A></TD>
165 man macro compiler library
166 <SPAN STYLE="font-size: smaller;">
167 (<A HREF="man.3.txt">text</A> |
168 <A HREF="man.3.xhtml">xhtml</A> |
169 <A HREF="man.3.pdf">pdf</A> |
170 <A HREF="man.3.ps">postscript</A>)
175 <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
177 man language reference
178 <SPAN STYLE="font-size: smaller;">
179 (<A HREF="man.7.txt">text</A> |
180 <A HREF="man.7.xhtml">xhtml</A> |
181 <A HREF="man.7.pdf">pdf</A> |
182 <A HREF="man.7.ps">postscript</A>)
187 <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
189 format and display UNIX manuals
190 <SPAN STYLE="font-size: smaller;">
191 (<A HREF="mandoc.1.txt">text</A> |
192 <A HREF="mandoc.1.xhtml">xhtml</A> |
193 <A HREF="mandoc.1.pdf">pdf</A> |
194 <A HREF="mandoc.1.ps">postscript</A>)
199 <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
201 mandoc special characters
202 <SPAN STYLE="font-size: smaller;">
203 (<A HREF="mandoc_char.7.txt">text</A> |
204 <A HREF="mandoc_char.7.xhtml">xhtml</A> |
205 <A HREF="mandoc_char.7.pdf">pdf</A> |
206 <A HREF="mandoc_char.7.ps">postscript</A>)
211 <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
213 mdoc macro compiler library
214 <SPAN STYLE="font-size: smaller;">
215 (<A HREF="mdoc.3.txt">text</A> |
216 <A HREF="mdoc.3.xhtml">xhtml</A> |
217 <A HREF="mdoc.3.pdf">pdf</A> |
218 <A HREF="mdoc.3.ps">postscript</A>)
223 <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
225 mdoc language reference
226 <SPAN STYLE="font-size: smaller;">
227 (<A HREF="mdoc.7.txt">text</A> |
228 <A HREF="mdoc.7.xhtml">xhtml</A> |
229 <A HREF="mdoc.7.pdf">pdf</A> |
230 <A HREF="mdoc.7.ps">postscript</A>)
235 <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
237 roff macro compiler library
238 <SPAN STYLE="font-size: smaller;">
239 (<A HREF="roff.3.txt">text</A> |
240 <A HREF="roff.3.xhtml">xhtml</A> |
241 <A HREF="roff.3.pdf">pdf</A> |
242 <A HREF="roff.3.ps">postscript</A>)
247 <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
249 roff-mandoc language reference
250 <SPAN STYLE="font-size: smaller;">
251 (<A HREF="roff.7.txt">text</A> |
252 <A HREF="roff.7.xhtml">xhtml</A> |
253 <A HREF="roff.7.pdf">pdf</A> |
254 <A HREF="roff.7.ps">postscript</A>)
262 See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
263 introduction to manpages and mdoc.
270 <A NAME="contact">CONTACT</A>
274 Please use the mailing lists for bug-reports, patches, questions, etc. Beyond that, contact
276 HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q=="
277 TITLE="Reveal this e-mail address">kris...</A>@bsd.lv.
281 You may also subscribe to several mailing lists (these require subscription, which is
285 <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
291 disc<A CLASS="external" TITLE="Reveal this e-mail address"
292 HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
295 bug-reports, general questions, and announcements
296 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/discuss/summary.html">archive</A>)</SPAN>
301 tec<A CLASS="external" TITLE="Reveal this e-mail address"
302 HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
305 patches and system discussions
306 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/tech/summary.html">archive</A>)</SPAN>
311 sou<A CLASS="external" TITLE="Reveal this e-mail address"
312 HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
315 source commit messages
316 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/source/summary.html">archive</A>)</SPAN>
326 <A NAME="news">NEWS</A>
330 <SPAN CLASS="date">23-12-2010</SPAN>:
334 Significant improvements merged from <A CLASS="external"
335 HREF="http://www.openbsd.org">OpenBSD</A> downstream, including
338 <LI>many new <A HREF="roff.7.html">roff</A> components,</LI>
339 <LI>in-line implementation of troff's soelim,</LI>
340 <LI>broken-block handling,</LI>
341 <LI>overhauled error classifications, and</LI>
342 <LI>cleaned up handling of error conditions.</LI>
345 Also overhauled the <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
346 CLASS="flag">-Txhtml</SPAN> output modes. They now display readable output in arbitrary
347 browsers, including text-based ones like <A CLASS="external"
348 HREF="http://lynx.isc.org">lynx</A>. See HTML and XHTML manuals in the <A
349 HREF="#documentation">DOCUMENTATION</A> section for examples. <SPAN
350 CLASS="attn">Attention: available style-sheet classes have been considerably
351 changed!</SPAN> See the <SPAN CLASS="file">example.style.css</SPAN> file for details.
352 Lastly, <A HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> have been
353 cleaned up and reduced in size and complexity.
358 <SPAN CLASS="date">27-09-2010</SPAN>:
362 Calling conventions for <A HREF="mandoc.1.html">mandoc</A> have changed: <SPAN
363 CLASS="flag">-W</SPAN> improved and <SPAN CLASS="flag">-f</SPAN> deprecated. Non-ASCII
364 characters are also now uniformly discarded. Lots of documentation improvements. Many
365 incremental fixes accomodating for groff's more interesting productions. Lastly, <A
366 HREF="http://perldoc.perl.org/pod2man.html" CLASS="external">pod2man</A> preambles are
367 now fully accepted after some considerable <A HREF="roff.7.html">roff</A> and special
373 <SPAN CLASS="date">27-07-2010</SPAN>:
377 Primarily a bug-fix and polish release, but including <SPAN CLASS="flag">-Tpdf</SPAN>
378 support in <A HREF="mandoc.1.html">mandoc</A> by way of <A CLASS="external"
379 HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">Summer of Code</A>.
383 <LI>fix <Q>Sm</Q> and <Q>Bd</Q> handling</LI>
384 <LI>fix end-of-sentence handling for embedded sentences</LI>
385 <LI>polish <A HREF="man.7.html">man</A> documentation</LI>
386 <LI>document all <A HREF="mdoc.7.html">mdoc</A> macros</LI>
387 <LI>polish <A HREF="mandoc.1.html">mandoc</A> <SPAN CLASS="flag">-Tps</SPAN> output</LI>
388 <LI>lots of internal clean-ups in character escapes</LI>
389 <LI>un-break literal contexts in <A HREF="man.7.html">man</A> documents</LI>
390 <LI>improve <SPAN CLASS="flag">-Thtml</SPAN> output for <SPAN CLASS="flag">-man</SPAN></LI>
391 <LI>add <A HREF="mandoc.1.html">mandoc</A> <SPAN CLASS="flag">-Tpdf</SPAN> support</LI>
396 <SPAN CLASS="date">12-07-2010</SPAN>:
400 Lots of features developed during both <A CLASS="external"
401 HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">Summer of Code</A> and the
402 <A CLASS="external" HREF="http://www.openbsd.org">OpenBSD</A> c2k10 hackathon:
405 <LI>minimal <Q>ds</Q> <A HREF="roff.7.html">roff</A> symbols are supported</LI>
406 <LI><Q>Bk</Q> <A HREF="mdoc.7.html">mdoc</A> support</LI>
407 <LI>beautified SYNOPSIS section output</LI>
408 <LI>variable font-width and paper-size support in <A HREF="mandoc.1.html">mandoc</A>
409 <SPAN CLASS="flag">-Tps</SPAN> output</LI>
410 <LI>acceptance of scope-block breakage in <A HREF="mdoc.7.html">mdoc</A></LI>
411 <LI>clarify error message status</LI>
412 <LI>many minor bug-fixes and formatting issues resolved</LI>
417 <SPAN CLASS="date">19-06-2010</SPAN>:
421 Small release featuring text-decoration in <SPAN CLASS="flag">-Tps</SPAN> output, a few
422 minor relaxations of errors, and some optimisations.
427 <SPAN CLASS="date">07-06-2010</SPAN>:
431 This primarily focusses on the <Q>Bl</Q> and <Q>It</Q> macros described in <A
432 HREF="mdoc.7.html">mdoc</A>. Multi-line column support is now fully compatible with
433 groff, as are implicit list entries for columns. Removed manuals.7 in favour of <A
434 CLASS="external" HREF="http://manpages.bsd.lv">http://manpages.bsd.lv</A>. The way we
435 handle the SYNOPSIS section (see the SYNOPSIS documentation in <A
436 HREF="mdoc.7.html#x4d414e55414cx20x535452554354555245">MANUAL STRUCTURE</A>) has also
437 been considerably simplified compared to groff's method. Furthermore, the <SPAN
438 CLASS="flag">-Owidth=width</SPAN> output option has been added to <SPAN
439 CLASS="flag">-Tascii</SPAN> (see <A HREF="mandoc.1.html">mandoc</A>). Lastly, initial
440 PostScript output has been added with the <SPAN CLASS="flag">-Tps</SPAN> option to <A
441 HREF="mandoc.1.html">mandoc</A>. It's brutally simple at the moment: fixed-font, with
447 <SPAN CLASS="date">29-05-2010</SPAN>:
451 Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD.
452 This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg
453 Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10.
454 Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:
457 <LI>a <A HREF="roff.3.html">libroff</A> preprocessor in front of <A
458 HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> stripping out
459 <A HREF="roff.7.html">roff</A> instructions;</LI>
460 <LI>end-of-sentence (EOS) detection in free-form and macro lines;</LI>
461 <LI>correct handling of tab-separated columnar lists in <SPAN
462 CLASS="flag">-mdoc</SPAN>;</LI>
463 <LI>improved main calling routines to optionally use mmap() for better
465 <LI>cleaned up exiting when invoked as <SPAN CLASS="flag">-Tlint</SPAN> or over
466 multiple files with <SPAN CLASS="flag">-fign-errors</SPAN>;</LI>
467 <LI>error and warning message handling re-written to be unified for <A
468 HREF="roff.3.html">libroff</A>, <A HREF="mdoc.3.html">libmdoc</A>, and <A
469 HREF="man.3.html">libman</A>;</LI>
470 <LI>handling of badly-nested explicit-scoped macros;</LI>
471 <LI>improved free-form text parsing in <A HREF="man.3.html">libman</A> and <A
472 HREF="mdoc.3.html">libmdoc</A>;</LI>
473 <LI>significant GNU troff compatibility improvements in <SPAN
474 CLASS="flag">-Tascii</SPAN>, largely in terms of spacing;</LI>
475 <LI>a regression framework for making sure the many fragilities of GNU troff
476 aren't trampled in subsequent work;</LI>
477 <LI>support for <SPAN CLASS="flag">-Tascii</SPAN> breaking at hyphens
478 encountered in free-form text;</LI>
479 <LI>and many more minor fixes and improvements (no really, consult <A
480 HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> and see
485 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
493 Copyright © 2008–2010 Kristaps Dzonsons, $Date: 2010/12/23 00:30:20 $