Annotation of mandoc/index.sgml, Revision 1.80
1.1 kristaps 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
1.40 kristaps 2: <HTML>
3: <HEAD>
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">
1.47 kristaps 7: <TITLE>mdocml | mdoc macro compiler</TITLE>
1.40 kristaps 8: </HEAD>
9: <BODY>
10: <TABLE CLASS="frame" SUMMARY="[frame]">
11: <COL WIDTH="100%">
12: <TBODY>
13: <TR>
14: <TD>
15: <DIV CLASS="head">
16: <B>mdocml</B> – mdoc macro compiler
17: </DIV>
1.75 kristaps 18: <DIV CLASS="subhead">
19: <A HREF="#description">Description</A> |
20: <A HREF="#sources">Sources</A> |
21: <A HREF="#documentation">Documentation</A> |
22: <A HREF="#contact">Contact</A> |
23: <A HREF="#news">News</A>
24: </DIV>
1.40 kristaps 25: </TD>
26: </TR>
27: <TR>
28: <TD VALIGN="top">
29: <H1>
1.75 kristaps 30: <A NAME="description">DESCRIPTION</A>
1.40 kristaps 31: </H1>
1.1 kristaps 32:
1.40 kristaps 33: <P>
34: <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <Q>-mdoc</Q>, the roff macro package
35: of choice for BSD manual pages, and <Q>-man</Q>, the predominant historical package for UNIX
36: manuals. The mission of <SPAN CLASS="nm">mdocml</SPAN> is to deprecate <A
37: HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU roff implementation, for
1.18 kristaps 38: displaying -mdoc pages whilst providing token support for -man.
1.40 kristaps 39: </P>
1.9 kristaps 40:
1.40 kristaps 41: <P>
1.13 kristaps 42: Why? groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL. It runs
43: slowly, produces uncertain output, and varies in operation from system to system. mdocml strives to fix
44: this (respectively small, C, ISC-licensed, fast and regular).
1.40 kristaps 45: </P>
1.1 kristaps 46:
1.40 kristaps 47: <P>
1.74 kristaps 48: The core of <SPAN CLASS="nm">mdocml</SPAN> is composed of the <A HREF="mdoc.3.html">libmdoc</A>, <A
49: HREF="man.3.html">libman</A>, and <A HREF="roff.3.html">libroff</A> validating compiler libraries. All
50: are simple, fast libraries operating on memory buffers, so they may be used for a variety of front-ends
51: (terminal-based, CGI and so on). The front-end is <A HREF="mandoc.1.html">mandoc</A>, which formats
52: manuals for display.
1.40 kristaps 53: </P>
54:
55: <P>
1.74 kristaps 56: The <SPAN CLASS="nm">mdocml</SPAN> suite is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv
1.40 kristaps 57: Project</A> member.
58: </P>
59: </TD>
60: </TR>
61: <TR>
62: <TD>
63: <H1>
1.75 kristaps 64: <A NAME="sources">SOURCES</A>
1.40 kristaps 65: </H1>
1.1 kristaps 66:
1.40 kristaps 67: <P>
1.74 kristaps 68: Sources correctly build and install on DragonFly BSD, FreeBSD, OpenBSD, NetBSD, GNU/Linux, and many
69: other operating systems, tested variously on i386, AMD64, alpha, and others. The most current version
70: is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>. A full <A
1.40 kristaps 71: HREF="ChangeLog.html">ChangeLog</A> (<A HREF="ChangeLog.txt">txt</A>) is written with each release.
72: </P>
1.7 kristaps 73:
1.40 kristaps 74: <H2>
1.26 kristaps 75: Current
1.40 kristaps 76: </H2>
1.1 kristaps 77:
1.40 kristaps 78: <TABLE WIDTH="100%" SUMMARY="Current Sources">
79: <COL WIDTH="200">
80: <COL>
81: <TBODY>
82: <TR>
83: <TD>Source archive</TD>
84: <TD>
85: <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
86: (<A HREF="/snapshots/mdocml.md5">md5</A>)
87: </TD>
88: </TR>
89: <TR>
90: <TD>Online source</TD>
91: <TD>
1.74 kristaps 92: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
1.40 kristaps 93: </TD>
94: </TR>
95: </TBODY>
96: </TABLE>
1.1 kristaps 97:
1.40 kristaps 98: <H2>
1.26 kristaps 99: Downstream
1.40 kristaps 100: </H2>
1.1 kristaps 101:
1.40 kristaps 102: <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
103: <COL WIDTH="200">
104: <COL>
105: <TBODY>
106: <TR>
107: <TD>DragonFly BSD</TD>
108: <TD>
109: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
110: CLASS="external">usr.bin/mandoc</A>
111: </TD>
112: </TR>
113: <TR>
114: <TD>FreeBSD</TD>
115: <TD>
116: <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
117: CLASS="external">ports/textproc/mdocml</A>
118: </TD>
119: </TR>
120: <TR>
121: <TD>NetBSD</TD>
122: <TD>
123: <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
124: CLASS="external">src/external/bsd/mdocml</A>
125: </TD>
126: </TR>
127: <TR>
128: <TD>OpenBSD</TD>
129: <TD>
130: <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
131: CLASS="external">src/usr.bin/mandoc</A>
132: </TD>
133: </TR>
134: </TBODY>
135: </TABLE>
1.1 kristaps 136:
1.40 kristaps 137: <H2>
1.22 kristaps 138: Historical
1.40 kristaps 139: </H2>
1.10 kristaps 140:
1.40 kristaps 141: <TABLE WIDTH="100%" SUMMARY="Archived Sources">
142: <COL WIDTH="200">
143: <COL>
144: <TBODY>
145: <TR>
146: <TD>Source archive</TD>
147: <TD>
148: <A HREF="/snapshots/">/snapshots/</A>
149: </TD>
150: </TR>
151: </TBODY>
152: </TABLE>
153: </TD>
154: </TR>
155: <TR>
156: <TD>
157: <H1>
1.75 kristaps 158: <A NAME="documentation">DOCUMENTATION</A>
1.40 kristaps 159: </H1>
1.18 kristaps 160:
1.40 kristaps 161: <P>
1.39 kristaps 162: These manuals are generated automatically and refer to the current snapshot.
1.40 kristaps 163: </P>
1.24 kristaps 164:
1.40 kristaps 165: <TABLE WIDTH="100%" SUMMARY="Documentation">
166: <COL WIDTH="200">
167: <COL>
168: <TBODY>
169: <TR>
1.80 ! kristaps 170: <TD VALIGN="top"><A HREF="man.3.html">man(3)</A></TD>
! 171: <TD VALIGN="top">
! 172: man macro compiler library
! 173: <DIV STYLE="font-size: smaller;">
! 174: <A HREF="man.3.txt">text</A> | <A HREF="man.3.ps">postscript</A>
! 175: </DIV>
! 176: </TD>
! 177: </TR>
! 178: <TR>
! 179: <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
! 180: <TD VALIGN="top">
! 181: man language reference
! 182: <DIV STYLE="font-size: smaller;">
! 183: <A HREF="man.7.txt">text</A> | <A HREF="man.7.ps">postscript</A>
! 184: </DIV>
! 185: </TD>
! 186: </TR>
! 187: <TR>
! 188: <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
! 189: <TD VALIGN="top">
! 190: format and display UNIX manuals
! 191: <DIV STYLE="font-size: smaller;">
! 192: <A HREF="mandoc.1.txt">text</A> | <A HREF="mandoc.1.ps">postscript</A>
! 193: </DIV>
! 194: </TD>
! 195: </TR>
! 196: <TR>
! 197: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
! 198: <TD VALIGN="top">
! 199: mandoc special characters
! 200: <DIV STYLE="font-size: smaller;">
! 201: <A HREF="mandoc_char.7.txt">text</A> | <A HREF="mandoc_char.7.ps">postscript</A>
! 202: </DIV>
! 203: </TD>
! 204: </TR>
! 205: <TR>
! 206: <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
! 207: <TD VALIGN="top">
! 208: mdoc macro compiler library
! 209: <DIV STYLE="font-size: smaller;">
! 210: <A HREF="mdoc.3.txt">text</A> | <A HREF="mdoc.3.ps">postscript</A>
! 211: </DIV>
! 212: </TD>
! 213: </TR>
! 214: <TR>
! 215: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
! 216: <TD VALIGN="top">
! 217: mdoc language reference
! 218: <DIV STYLE="font-size: smaller;">
! 219: <A HREF="mdoc.7.txt">text</A> | <A HREF="mdoc.7.ps">postscript</A>
! 220: </DIV>
! 221: </TD>
! 222: </TR>
! 223: <TR>
! 224: <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
! 225: <TD VALIGN="top">
! 226: roff macro compiler library
! 227: <DIV STYLE="font-size: smaller;">
! 228: <A HREF="roff.3.txt">text</A> | <A HREF="roff.3.ps">postscript</A>
! 229: </DIV>
! 230: </TD>
! 231: </TR>
! 232: <TR>
! 233: <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
! 234: <TD VALIGN="top">
! 235: roff-mandoc language reference
! 236: <DIV STYLE="font-size: smaller;">
! 237: <A HREF="roff.7.txt">text</A> | <A HREF="roff.7.ps">postscript</A>
! 238: </DIV>
! 239: </TD>
1.71 kristaps 240: </TR>
1.40 kristaps 241: </TBODY>
242: </TABLE>
1.79 kristaps 243:
244: <P>
245: See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
246: introduction to manpages and mdoc.
1.40 kristaps 247: </TD>
248: </TR>
249: <TR>
250: <TD>
251: <H1>
1.75 kristaps 252: <A NAME="contact">CONTACT</A>
1.40 kristaps 253: </H1>
1.1 kristaps 254:
1.40 kristaps 255: <P>
256: For all issues related to <SPAN CLASS="nm">mdocml</SPAN>, contact Kristaps Dzonsons, kris<A
257: CLASS="external"
258: HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q=="
259: TITLE="Reveal this e-mail address">...</A>@bsd.lv.
260: </P>
1.18 kristaps 261:
1.40 kristaps 262: <P>
1.68 kristaps 263: You may also subscribe to several mailing lists (these require subscription, which is moderated). An
1.74 kristaps 264: archive is not yet available on-line, although you may request one once subscribed.
1.40 kristaps 265: </P>
1.57 kristaps 266:
267: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
268: <COL WIDTH="200">
269: <COL>
270: <TBODY>
271: <TR>
272: <TD>
1.60 kristaps 273: disc<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 274: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
1.57 kristaps 275: </TD>
1.72 kristaps 276: <TD>high-level discussions and version announcements</TD>
277: </TR>
278: <TR>
279: <TD>
280: tec<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 281: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
1.72 kristaps 282: </TD>
283: <TD>low-level discussions</TD>
1.58 kristaps 284: </TR>
1.67 kristaps 285: <TR>
1.58 kristaps 286: <TD>
287: sou<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 288: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
1.58 kristaps 289: </TD>
1.59 kristaps 290: <TD>source commit messages</TD>
1.67 kristaps 291: </TR>
1.57 kristaps 292: </TBODY>
293: </TABLE>
1.40 kristaps 294: </TD>
295: </TR>
296: <TR>
297: <TD>
298: <H1>
1.75 kristaps 299: <A NAME="news">NEWS</A>
1.40 kristaps 300: </H1>
1.77 kristaps 301: <DIV CLASS="news">
1.80 ! kristaps 302: </DIV>
1.77 kristaps 303: <P>
1.79 kristaps 304: <SPAN CLASS="date">07-06-2010</SPAN>:
1.77 kristaps 305: version 1.10.1
306: </P>
307: <P>
308: This primarily focusses on the <Q>Bl</Q> and <Q>It</Q> macros described in <A
309: HREF="mdoc.7.html">mdoc</A>. Multi-line column support is now fully compatible with
1.78 kristaps 310: groff, as are implicit list entries for columns. Removed manuals.7 in favour of <A
1.79 kristaps 311: CLASS="external" HREF="http://manpages.bsd.lv">http://manpages.bsd.lv</A>. The way we
312: handle the SYNOPSIS section (see the SYNOPSIS documentation in <A
313: HREF="mdoc.7.html#x4d414e55414cx20x535452554354555245">MANUAL STRUCTURE</A>) has also
1.80 ! kristaps 314: been considerably simplified compared to groff's method. Furthermore, the <SPAN
1.79 kristaps 315: CLASS="flag">-Owidth=width</SPAN> output option has been added to <SPAN
1.80 ! kristaps 316: CLASS="flag">-Tascii</SPAN> (see <A HREF="mandoc.1.html">mandoc</A>). Lastly, initial
! 317: PostScript output has been added with the <SPAN CLASS="flag">-Tps</SPAN> option to <A
! 318: HREF="mandoc.1.html">mandoc</A>. It's brutally simple at the moment: fixed-font, with
! 319: no font decorations.
1.77 kristaps 320: </P>
321: </DIV>
1.75 kristaps 322: <DIV CLASS="news">
323: <P>
324: <SPAN CLASS="date">29-05-2010</SPAN>:
325: version 1.10.0
326: </P>
327: <P>
328: Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD.
329: This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg
330: Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10.
331: Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:
332: </P>
333: <UL>
334: <LI>a <A HREF="roff.3.html">libroff</A> preprocessor in front of <A
335: HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> stripping out
336: <A HREF="roff.7.html">roff</A> instructions;</LI>
337: <LI>end-of-sentence (EOS) detection in free-form and macro lines;</LI>
338: <LI>correct handling of tab-separated columnar lists in <SPAN
339: CLASS="flag">-mdoc</SPAN>;</LI>
340: <LI>improved main calling routines to optionally use mmap() for better
341: performance;</LI>
342: <LI>cleaned up exiting when invoked as <SPAN CLASS="flag">-Tlint</SPAN> or over
343: multiple files with <SPAN CLASS="flag">-fign-errors</SPAN>;</LI>
344: <LI>error and warning message handling re-written to be unified for <A
345: HREF="roff.3.html">libroff</A>, <A HREF="mdoc.3.html">libmdoc</A>, and <A
346: HREF="man.3.html">libman</A>;</LI>
347: <LI>handling of badly-nested explicit-scoped macros;</LI>
348: <LI>improved free-form text parsing in <A HREF="man.3.html">libman</A> and <A
349: HREF="mdoc.3.html">libmdoc</A>;</LI>
350: <LI>significant GNU troff compatibility improvements in <SPAN
351: CLASS="flag">-Tascii</SPAN>, largely in terms of spacing;</LI>
352: <LI>a regression framework for making sure the many fragilities of GNU troff
353: aren't trampled in subsequent work;</LI>
354: <LI>support for <SPAN CLASS="flag">-Tascii</SPAN> breaking at hyphens
355: encountered in free-form text;</LI>
356: <LI>and many more minor fixes and improvements (no really, consult <A
357: HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> and see
358: for yourself!).</LI>
359: </UL>
360: </DIV>
361: <DIV CLASS="news">
362: <P>
363: <SPAN CLASS="date">13-05-2010</SPAN>:
364: version 1.9.25
365: </P>
366: <P>
367: Fixed handling of <Q>\*(Ba</Q> escape. Backed out <SPAN
368: CLASS="flag">-fno-ign-chars</SPAN> (pointless complexity). Fixed erroneous
369: breaking of literal lines. Fixed SYNOPSIS breaking lines before non-initial
370: macros. Changed default section ordering. Most importantly, the framework for
371: end-of-sentence double-spacing is in place, now implemented for the
372: <Q>end-of-sentence, end-of-line</Q> rule. This is a stable roll-back point
373: before the mandoc hackathon in Rostock!
374: </P>
375: </DIV>
376: <DIV CLASS="news">
377: <P>
378: <SPAN CLASS="date">09-05-2010</SPAN>:
379: version 1.9.24
380: </P>
381: <P>
382: Rolled back break-at-hyphen. <SPAN CLASS="flag">-DUGLY</SPAN> is now the
383: default (no feature splits!). Free-form text is not de-chunked any more: lines
384: are passed whole-sale into the front-end, including whitespace. Added mailing
385: lists. Lastly, <SPAN CLASS="nm">mdocml</SPAN> is the focus of two <A
386: CLASS="external" HREF="http://socghop.appspot.com/">Google Summer of Code</A>
387: projects this year: <Q><A CLASS="external"
388: HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">mandoc -Tps</A></Q>
389: (NetBSD) and <Q><A CLASS="external"
390: HREF="http://wiki.freebsd.org/SummerOfCode2010Projects">BSD-licensed
391: Text-Processing Tools</A></Q> (FreeBSD).
392: </P>
393: </DIV>
394: <P>
395: See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
396: historical notes.
397: </P>
1.40 kristaps 398: </TD>
399: </TR>
400: <TR>
401: <TD>
402: <DIV CLASS="foot">
1.80 ! kristaps 403: Copyright © 2008–2010 Kristaps Dzonsons, $Date: 2010/06/07 12:20:07 $
1.40 kristaps 404: </DIV>
405: </TD>
406: </TR>
407: </TBODY>
408: </TABLE>
409: </BODY>
410: </HTML>
CVSweb