Annotation of mandoc/index.sgml, Revision 1.91
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>
18: </TD>
19: </TR>
20: <TR>
21: <TD VALIGN="top">
22: <H1>
1.75 kristaps 23: <A NAME="description">DESCRIPTION</A>
1.40 kristaps 24: </H1>
1.1 kristaps 25:
1.40 kristaps 26: <P>
1.84 kristaps 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.
1.40 kristaps 32: </P>
1.9 kristaps 33:
1.40 kristaps 34: <P>
1.13 kristaps 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
1.84 kristaps 37: this (respectively small, C, <A CLASS="external"
38: HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
1.40 kristaps 39: </P>
1.1 kristaps 40:
1.40 kristaps 41: <P>
1.84 kristaps 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, and PostScript. <SPAN CLASS="nm">mdocml</SPAN> is a <A CLASS="external"
46: HREF="http://bsd.lv/">BSD.lv</A> project.
1.40 kristaps 47: </P>
48:
49: <P>
1.84 kristaps 50: <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary,
51: <Q>mandoc</Q>.
1.40 kristaps 52: </P>
53: </TD>
54: </TR>
55: <TR>
56: <TD>
57: <H1>
1.75 kristaps 58: <A NAME="sources">SOURCES</A>
1.40 kristaps 59: </H1>
1.1 kristaps 60:
1.40 kristaps 61: <P>
1.84 kristaps 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.
1.40 kristaps 65: </P>
1.7 kristaps 66:
1.40 kristaps 67: <H2>
1.26 kristaps 68: Current
1.40 kristaps 69: </H2>
1.1 kristaps 70:
1.40 kristaps 71: <TABLE WIDTH="100%" SUMMARY="Current Sources">
72: <COL WIDTH="200">
73: <COL>
74: <TBODY>
75: <TR>
76: <TD>Source archive</TD>
77: <TD>
78: <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
79: (<A HREF="/snapshots/mdocml.md5">md5</A>)
80: </TD>
81: </TR>
82: <TR>
83: <TD>Online source</TD>
84: <TD>
1.74 kristaps 85: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
1.40 kristaps 86: </TD>
87: </TR>
88: </TBODY>
89: </TABLE>
1.1 kristaps 90:
1.40 kristaps 91: <H2>
1.26 kristaps 92: Downstream
1.40 kristaps 93: </H2>
1.1 kristaps 94:
1.40 kristaps 95: <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
96: <COL WIDTH="200">
97: <COL>
98: <TBODY>
99: <TR>
100: <TD>DragonFly BSD</TD>
101: <TD>
102: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
103: CLASS="external">usr.bin/mandoc</A>
104: </TD>
105: </TR>
106: <TR>
107: <TD>FreeBSD</TD>
108: <TD>
109: <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
110: CLASS="external">ports/textproc/mdocml</A>
111: </TD>
112: </TR>
113: <TR>
114: <TD>NetBSD</TD>
115: <TD>
116: <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
117: CLASS="external">src/external/bsd/mdocml</A>
118: </TD>
119: </TR>
120: <TR>
121: <TD>OpenBSD</TD>
122: <TD>
123: <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
124: CLASS="external">src/usr.bin/mandoc</A>
125: </TD>
126: </TR>
127: </TBODY>
128: </TABLE>
1.1 kristaps 129:
1.40 kristaps 130: <H2>
1.22 kristaps 131: Historical
1.40 kristaps 132: </H2>
1.10 kristaps 133:
1.40 kristaps 134: <TABLE WIDTH="100%" SUMMARY="Archived Sources">
135: <COL WIDTH="200">
136: <COL>
137: <TBODY>
138: <TR>
139: <TD>Source archive</TD>
140: <TD>
141: <A HREF="/snapshots/">/snapshots/</A>
142: </TD>
143: </TR>
144: </TBODY>
145: </TABLE>
146: </TD>
147: </TR>
148: <TR>
149: <TD>
150: <H1>
1.75 kristaps 151: <A NAME="documentation">DOCUMENTATION</A>
1.40 kristaps 152: </H1>
1.18 kristaps 153:
1.40 kristaps 154: <P>
1.84 kristaps 155: These manuals are generated automatically and refer to the current snapshot.
1.40 kristaps 156: </P>
1.24 kristaps 157:
1.40 kristaps 158: <TABLE WIDTH="100%" SUMMARY="Documentation">
159: <COL WIDTH="200">
160: <COL>
161: <TBODY>
162: <TR>
1.80 kristaps 163: <TD VALIGN="top"><A HREF="man.3.html">man(3)</A></TD>
164: <TD VALIGN="top">
165: man macro compiler library
1.84 kristaps 166: <SPAN STYLE="font-size: smaller;">
1.91 ! kristaps 167: (<A HREF="man.3.txt">text</A> |
! 168: <A HREF="man.3.pdf">pdf</A> |
! 169: <A HREF="man.3.ps">postscript</A>)
1.84 kristaps 170: </SPAN>
1.80 kristaps 171: </TD>
172: </TR>
173: <TR>
174: <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
175: <TD VALIGN="top">
176: man language reference
1.84 kristaps 177: <SPAN STYLE="font-size: smaller;">
1.91 ! kristaps 178: (<A HREF="man.7.txt">text</A> |
! 179: <A HREF="man.7.pdf">pdf</A> |
! 180: <A HREF="man.7.ps">postscript</A>)
1.84 kristaps 181: </SPAN>
1.80 kristaps 182: </TD>
183: </TR>
184: <TR>
185: <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
186: <TD VALIGN="top">
187: format and display UNIX manuals
1.84 kristaps 188: <SPAN STYLE="font-size: smaller;">
1.91 ! kristaps 189: (<A HREF="mandoc.1.txt">text</A> |
! 190: <A HREF="mandoc.1.pdf">pdf</A> |
! 191: <A HREF="mandoc.1.ps">postscript</A>)
1.84 kristaps 192: </SPAN>
1.80 kristaps 193: </TD>
194: </TR>
195: <TR>
196: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
197: <TD VALIGN="top">
198: mandoc special characters
1.84 kristaps 199: <SPAN STYLE="font-size: smaller;">
1.91 ! kristaps 200: (<A HREF="mandoc_char.7.txt">text</A> |
! 201: <A HREF="mandoc_char.7.pdf">pdf</A> |
! 202: <A HREF="mandoc_char.7.ps">postscript</A>)
1.84 kristaps 203: </SPAN>
1.80 kristaps 204: </TD>
205: </TR>
206: <TR>
207: <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
208: <TD VALIGN="top">
209: mdoc macro compiler library
1.84 kristaps 210: <SPAN STYLE="font-size: smaller;">
1.91 ! kristaps 211: (<A HREF="mdoc.3.txt">text</A> |
! 212: <A HREF="mdoc.3.pdf">pdf</A> |
! 213: <A HREF="mdoc.3.ps">postscript</A>)
1.84 kristaps 214: </SPAN>
1.80 kristaps 215: </TD>
216: </TR>
217: <TR>
218: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
219: <TD VALIGN="top">
220: mdoc language reference
1.84 kristaps 221: <SPAN STYLE="font-size: smaller;">
1.91 ! kristaps 222: (<A HREF="mdoc.7.txt">text</A> |
! 223: <A HREF="mdoc.7.pdf">pdf</A> |
! 224: <A HREF="mdoc.7.ps">postscript</A>)
1.84 kristaps 225: </SPAN>
1.80 kristaps 226: </TD>
227: </TR>
228: <TR>
229: <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
230: <TD VALIGN="top">
231: roff macro compiler library
1.84 kristaps 232: <SPAN STYLE="font-size: smaller;">
1.91 ! kristaps 233: (<A HREF="roff.3.txt">text</A> |
! 234: <A HREF="roff.3.pdf">pdf</A> |
! 235: <A HREF="roff.3.ps">postscript</A>)
1.84 kristaps 236: </SPAN>
1.80 kristaps 237: </TD>
238: </TR>
239: <TR>
240: <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
241: <TD VALIGN="top">
242: roff-mandoc language reference
1.84 kristaps 243: <SPAN STYLE="font-size: smaller;">
1.91 ! kristaps 244: (<A HREF="roff.7.txt">text</A> |
! 245: <A HREF="roff.7.pdf">pdf</A> |
! 246: <A HREF="roff.7.ps">postscript</A>)
1.84 kristaps 247: </SPAN>
1.80 kristaps 248: </TD>
1.71 kristaps 249: </TR>
1.40 kristaps 250: </TBODY>
251: </TABLE>
1.79 kristaps 252:
253: <P>
254: See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
255: introduction to manpages and mdoc.
1.82 kristaps 256: </P>
1.40 kristaps 257: </TD>
258: </TR>
259: <TR>
260: <TD>
261: <H1>
1.75 kristaps 262: <A NAME="contact">CONTACT</A>
1.40 kristaps 263: </H1>
1.1 kristaps 264:
1.40 kristaps 265: <P>
1.84 kristaps 266: Please use the mailing lists for bug-reports, patches, questions, etc. Beyond that, contact
267: Kristaps at <A
268: HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q=="
269: TITLE="Reveal this e-mail address">kris...</A>@bsd.lv.
1.40 kristaps 270: </P>
1.18 kristaps 271:
1.40 kristaps 272: <P>
1.84 kristaps 273: You may also subscribe to several mailing lists (these require subscription, which is
274: moderated). An archive is not yet available on-line, although you may request one once
275: subscribed.
1.40 kristaps 276: </P>
1.57 kristaps 277:
278: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
279: <COL WIDTH="200">
280: <COL>
281: <TBODY>
282: <TR>
283: <TD>
1.60 kristaps 284: disc<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 285: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
1.57 kristaps 286: </TD>
1.85 kristaps 287: <TD>bug-reports, general questions, and announcements</TD>
1.72 kristaps 288: </TR>
289: <TR>
290: <TD>
291: tec<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 292: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
1.72 kristaps 293: </TD>
1.85 kristaps 294: <TD>patches and system discussions</TD>
1.58 kristaps 295: </TR>
1.67 kristaps 296: <TR>
1.58 kristaps 297: <TD>
298: sou<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 299: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
1.58 kristaps 300: </TD>
1.59 kristaps 301: <TD>source commit messages</TD>
1.67 kristaps 302: </TR>
1.57 kristaps 303: </TBODY>
304: </TABLE>
1.40 kristaps 305: </TD>
306: </TR>
307: <TR>
308: <TD>
309: <H1>
1.75 kristaps 310: <A NAME="news">NEWS</A>
1.40 kristaps 311: </H1>
1.77 kristaps 312: <DIV CLASS="news">
313: <P>
1.89 kristaps 314: <SPAN CLASS="date">27-07-2010</SPAN>:
1.86 kristaps 315: version 1.10.5
316: </P>
317: <P>
1.89 kristaps 318: Primarily a bug-fix and polish release, but including <SPAN CLASS="flag">-Tpdf</SPAN>
319: support in <A HREF="mandoc.1.html">mandoc</A> by way of <A CLASS="external"
320: HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">Summer of Code</A>.
321: Highlights:
1.86 kristaps 322: </P>
323: <UL>
1.89 kristaps 324: <LI>fix <Q>Sm</Q> and <Q>Bd</Q> handling</LI>
1.86 kristaps 325: <LI>fix end-of-sentence handling for embedded sentences</LI>
326: <LI>polish <A HREF="man.7.html">man</A> documentation</LI>
327: <LI>document all <A HREF="mdoc.7.html">mdoc</A> macros</LI>
1.89 kristaps 328: <LI>polish <A HREF="mandoc.1.html">mandoc</A> <SPAN CLASS="flag">-Tps</SPAN> output</LI>
1.86 kristaps 329: <LI>lots of internal clean-ups in character escapes</LI>
330: <LI>un-break literal contexts in <A HREF="man.7.html">man</A> documents</LI>
1.90 kristaps 331: <LI>improve <SPAN CLASS="flag">-Thtml</SPAN> output for <SPAN CLASS="flag">-man</SPAN></LI>
1.89 kristaps 332: <LI>add <A HREF="mandoc.1.html">mandoc</A> <SPAN CLASS="flag">-Tpdf</SPAN> support</LI>
1.86 kristaps 333: </UL>
334: </DIV>
335: <DIV CLASS="news">
336: <P>
1.83 kristaps 337: <SPAN CLASS="date">12-07-2010</SPAN>:
338: version 1.10.4
339: </P>
340: <P>
341: Lots of features developed during both <A CLASS="external"
342: HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">Summer of Code</A> and the
343: <A CLASS="external" HREF="http://www.openbsd.org">OpenBSD</A> c2k10 hackathon:
344: </P>
345: <UL>
346: <LI>minimal <Q>ds</Q> <A HREF="roff.7.html">roff</A> symbols are supported</LI>
347: <LI><Q>Bk</Q> <A HREF="mdoc.7.html">mdoc</A> support</LI>
348: <LI>beautified SYNOPSIS section output</LI>
349: <LI>variable font-width and paper-size support in <A HREF="mandoc.1.html">mandoc</A>
1.90 kristaps 350: <SPAN CLASS="flag">-Tps</SPAN> output</LI>
1.83 kristaps 351: <LI>acceptance of scope-block breakage in <A HREF="mdoc.7.html">mdoc</A></LI>
352: <LI>clarify error message status</LI>
353: <LI>many minor bug-fixes and formatting issues resolved</LI>
354: </UL>
355: </DIV>
356: <DIV CLASS="news">
357: <P>
1.82 kristaps 358: <SPAN CLASS="date">19-06-2010</SPAN>:
359: version 1.10.2
360: </P>
361: <P>
362: Small release featuring text-decoration in <SPAN CLASS="flag">-Tps</SPAN> output, a few
363: minor relaxations of errors, and some optimisations.
364: </P>
365: </DIV>
366: <DIV CLASS="news">
367: <P>
1.79 kristaps 368: <SPAN CLASS="date">07-06-2010</SPAN>:
1.77 kristaps 369: version 1.10.1
370: </P>
371: <P>
372: This primarily focusses on the <Q>Bl</Q> and <Q>It</Q> macros described in <A
373: HREF="mdoc.7.html">mdoc</A>. Multi-line column support is now fully compatible with
1.78 kristaps 374: groff, as are implicit list entries for columns. Removed manuals.7 in favour of <A
1.79 kristaps 375: CLASS="external" HREF="http://manpages.bsd.lv">http://manpages.bsd.lv</A>. The way we
376: handle the SYNOPSIS section (see the SYNOPSIS documentation in <A
377: HREF="mdoc.7.html#x4d414e55414cx20x535452554354555245">MANUAL STRUCTURE</A>) has also
1.80 kristaps 378: been considerably simplified compared to groff's method. Furthermore, the <SPAN
1.79 kristaps 379: CLASS="flag">-Owidth=width</SPAN> output option has been added to <SPAN
1.80 kristaps 380: CLASS="flag">-Tascii</SPAN> (see <A HREF="mandoc.1.html">mandoc</A>). Lastly, initial
381: PostScript output has been added with the <SPAN CLASS="flag">-Tps</SPAN> option to <A
382: HREF="mandoc.1.html">mandoc</A>. It's brutally simple at the moment: fixed-font, with
383: no font decorations.
1.77 kristaps 384: </P>
385: </DIV>
1.75 kristaps 386: <DIV CLASS="news">
387: <P>
388: <SPAN CLASS="date">29-05-2010</SPAN>:
389: version 1.10.0
390: </P>
391: <P>
392: Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD.
393: This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg
394: Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10.
395: Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:
396: </P>
397: <UL>
398: <LI>a <A HREF="roff.3.html">libroff</A> preprocessor in front of <A
399: HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> stripping out
400: <A HREF="roff.7.html">roff</A> instructions;</LI>
401: <LI>end-of-sentence (EOS) detection in free-form and macro lines;</LI>
402: <LI>correct handling of tab-separated columnar lists in <SPAN
403: CLASS="flag">-mdoc</SPAN>;</LI>
404: <LI>improved main calling routines to optionally use mmap() for better
405: performance;</LI>
406: <LI>cleaned up exiting when invoked as <SPAN CLASS="flag">-Tlint</SPAN> or over
407: multiple files with <SPAN CLASS="flag">-fign-errors</SPAN>;</LI>
408: <LI>error and warning message handling re-written to be unified for <A
409: HREF="roff.3.html">libroff</A>, <A HREF="mdoc.3.html">libmdoc</A>, and <A
410: HREF="man.3.html">libman</A>;</LI>
411: <LI>handling of badly-nested explicit-scoped macros;</LI>
412: <LI>improved free-form text parsing in <A HREF="man.3.html">libman</A> and <A
413: HREF="mdoc.3.html">libmdoc</A>;</LI>
414: <LI>significant GNU troff compatibility improvements in <SPAN
415: CLASS="flag">-Tascii</SPAN>, largely in terms of spacing;</LI>
416: <LI>a regression framework for making sure the many fragilities of GNU troff
417: aren't trampled in subsequent work;</LI>
418: <LI>support for <SPAN CLASS="flag">-Tascii</SPAN> breaking at hyphens
419: encountered in free-form text;</LI>
420: <LI>and many more minor fixes and improvements (no really, consult <A
421: HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> and see
422: for yourself!).</LI>
423: </UL>
424: </DIV>
425: <P>
426: See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
427: historical notes.
428: </P>
1.40 kristaps 429: </TD>
430: </TR>
431: <TR>
432: <TD>
433: <DIV CLASS="foot">
1.91 ! kristaps 434: Copyright © 2008–2010 Kristaps Dzonsons, $Date: 2010/07/27 20:02:52 $
1.40 kristaps 435: </DIV>
436: </TD>
437: </TR>
438: </TBODY>
439: </TABLE>
440: </BODY>
441: </HTML>
CVSweb