Annotation of mandoc/index.sgml, Revision 1.83
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.82 kristaps 247: </P>
1.40 kristaps 248: </TD>
249: </TR>
250: <TR>
251: <TD>
252: <H1>
1.75 kristaps 253: <A NAME="contact">CONTACT</A>
1.40 kristaps 254: </H1>
1.1 kristaps 255:
1.40 kristaps 256: <P>
257: For all issues related to <SPAN CLASS="nm">mdocml</SPAN>, contact Kristaps Dzonsons, kris<A
258: CLASS="external"
259: HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q=="
260: TITLE="Reveal this e-mail address">...</A>@bsd.lv.
261: </P>
1.18 kristaps 262:
1.40 kristaps 263: <P>
1.68 kristaps 264: You may also subscribe to several mailing lists (these require subscription, which is moderated). An
1.74 kristaps 265: archive is not yet available on-line, although you may request one once subscribed.
1.40 kristaps 266: </P>
1.57 kristaps 267:
268: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
269: <COL WIDTH="200">
270: <COL>
271: <TBODY>
272: <TR>
273: <TD>
1.60 kristaps 274: disc<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 275: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
1.57 kristaps 276: </TD>
1.72 kristaps 277: <TD>high-level discussions and version announcements</TD>
278: </TR>
279: <TR>
280: <TD>
281: tec<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 282: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
1.72 kristaps 283: </TD>
284: <TD>low-level discussions</TD>
1.58 kristaps 285: </TR>
1.67 kristaps 286: <TR>
1.58 kristaps 287: <TD>
288: sou<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 289: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
1.58 kristaps 290: </TD>
1.59 kristaps 291: <TD>source commit messages</TD>
1.67 kristaps 292: </TR>
1.57 kristaps 293: </TBODY>
294: </TABLE>
1.40 kristaps 295: </TD>
296: </TR>
297: <TR>
298: <TD>
299: <H1>
1.75 kristaps 300: <A NAME="news">NEWS</A>
1.40 kristaps 301: </H1>
1.77 kristaps 302: <DIV CLASS="news">
303: <P>
1.83 ! kristaps 304: <SPAN CLASS="date">12-07-2010</SPAN>:
! 305: version 1.10.4
! 306: </P>
! 307: <P>
! 308: Lots of features developed during both <A CLASS="external"
! 309: HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">Summer of Code</A> and the
! 310: <A CLASS="external" HREF="http://www.openbsd.org">OpenBSD</A> c2k10 hackathon:
! 311: </P>
! 312: <UL>
! 313: <LI>minimal <Q>ds</Q> <A HREF="roff.7.html">roff</A> symbols are supported</LI>
! 314: <LI><Q>Bk</Q> <A HREF="mdoc.7.html">mdoc</A> support</LI>
! 315: <LI>beautified SYNOPSIS section output</LI>
! 316: <LI>variable font-width and paper-size support in <A HREF="mandoc.1.html">mandoc</A>
! 317: -Tps output</LI>
! 318: <LI>acceptance of scope-block breakage in <A HREF="mdoc.7.html">mdoc</A></LI>
! 319: <LI>clarify error message status</LI>
! 320: <LI>many minor bug-fixes and formatting issues resolved</LI>
! 321: </UL>
! 322: </DIV>
! 323: <DIV CLASS="news">
! 324: <P>
1.82 kristaps 325: <SPAN CLASS="date">19-06-2010</SPAN>:
326: version 1.10.2
327: </P>
328: <P>
329: Small release featuring text-decoration in <SPAN CLASS="flag">-Tps</SPAN> output, a few
330: minor relaxations of errors, and some optimisations.
331: </P>
332: </DIV>
333: <DIV CLASS="news">
334: <P>
1.79 kristaps 335: <SPAN CLASS="date">07-06-2010</SPAN>:
1.77 kristaps 336: version 1.10.1
337: </P>
338: <P>
339: This primarily focusses on the <Q>Bl</Q> and <Q>It</Q> macros described in <A
340: HREF="mdoc.7.html">mdoc</A>. Multi-line column support is now fully compatible with
1.78 kristaps 341: groff, as are implicit list entries for columns. Removed manuals.7 in favour of <A
1.79 kristaps 342: CLASS="external" HREF="http://manpages.bsd.lv">http://manpages.bsd.lv</A>. The way we
343: handle the SYNOPSIS section (see the SYNOPSIS documentation in <A
344: HREF="mdoc.7.html#x4d414e55414cx20x535452554354555245">MANUAL STRUCTURE</A>) has also
1.80 kristaps 345: been considerably simplified compared to groff's method. Furthermore, the <SPAN
1.79 kristaps 346: CLASS="flag">-Owidth=width</SPAN> output option has been added to <SPAN
1.80 kristaps 347: CLASS="flag">-Tascii</SPAN> (see <A HREF="mandoc.1.html">mandoc</A>). Lastly, initial
348: PostScript output has been added with the <SPAN CLASS="flag">-Tps</SPAN> option to <A
349: HREF="mandoc.1.html">mandoc</A>. It's brutally simple at the moment: fixed-font, with
350: no font decorations.
1.77 kristaps 351: </P>
352: </DIV>
1.75 kristaps 353: <DIV CLASS="news">
354: <P>
355: <SPAN CLASS="date">29-05-2010</SPAN>:
356: version 1.10.0
357: </P>
358: <P>
359: Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD.
360: This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg
361: Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10.
362: Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:
363: </P>
364: <UL>
365: <LI>a <A HREF="roff.3.html">libroff</A> preprocessor in front of <A
366: HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> stripping out
367: <A HREF="roff.7.html">roff</A> instructions;</LI>
368: <LI>end-of-sentence (EOS) detection in free-form and macro lines;</LI>
369: <LI>correct handling of tab-separated columnar lists in <SPAN
370: CLASS="flag">-mdoc</SPAN>;</LI>
371: <LI>improved main calling routines to optionally use mmap() for better
372: performance;</LI>
373: <LI>cleaned up exiting when invoked as <SPAN CLASS="flag">-Tlint</SPAN> or over
374: multiple files with <SPAN CLASS="flag">-fign-errors</SPAN>;</LI>
375: <LI>error and warning message handling re-written to be unified for <A
376: HREF="roff.3.html">libroff</A>, <A HREF="mdoc.3.html">libmdoc</A>, and <A
377: HREF="man.3.html">libman</A>;</LI>
378: <LI>handling of badly-nested explicit-scoped macros;</LI>
379: <LI>improved free-form text parsing in <A HREF="man.3.html">libman</A> and <A
380: HREF="mdoc.3.html">libmdoc</A>;</LI>
381: <LI>significant GNU troff compatibility improvements in <SPAN
382: CLASS="flag">-Tascii</SPAN>, largely in terms of spacing;</LI>
383: <LI>a regression framework for making sure the many fragilities of GNU troff
384: aren't trampled in subsequent work;</LI>
385: <LI>support for <SPAN CLASS="flag">-Tascii</SPAN> breaking at hyphens
386: encountered in free-form text;</LI>
387: <LI>and many more minor fixes and improvements (no really, consult <A
388: HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> and see
389: for yourself!).</LI>
390: </UL>
391: </DIV>
392: <DIV CLASS="news">
393: <P>
394: <SPAN CLASS="date">13-05-2010</SPAN>:
395: version 1.9.25
396: </P>
397: <P>
398: Fixed handling of <Q>\*(Ba</Q> escape. Backed out <SPAN
399: CLASS="flag">-fno-ign-chars</SPAN> (pointless complexity). Fixed erroneous
400: breaking of literal lines. Fixed SYNOPSIS breaking lines before non-initial
401: macros. Changed default section ordering. Most importantly, the framework for
402: end-of-sentence double-spacing is in place, now implemented for the
403: <Q>end-of-sentence, end-of-line</Q> rule. This is a stable roll-back point
404: before the mandoc hackathon in Rostock!
405: </P>
406: </DIV>
407: <DIV CLASS="news">
408: <P>
409: <SPAN CLASS="date">09-05-2010</SPAN>:
410: version 1.9.24
411: </P>
412: <P>
413: Rolled back break-at-hyphen. <SPAN CLASS="flag">-DUGLY</SPAN> is now the
414: default (no feature splits!). Free-form text is not de-chunked any more: lines
415: are passed whole-sale into the front-end, including whitespace. Added mailing
416: lists. Lastly, <SPAN CLASS="nm">mdocml</SPAN> is the focus of two <A
417: CLASS="external" HREF="http://socghop.appspot.com/">Google Summer of Code</A>
418: projects this year: <Q><A CLASS="external"
419: HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">mandoc -Tps</A></Q>
420: (NetBSD) and <Q><A CLASS="external"
421: HREF="http://wiki.freebsd.org/SummerOfCode2010Projects">BSD-licensed
422: Text-Processing Tools</A></Q> (FreeBSD).
423: </P>
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.83 ! kristaps 434: Copyright © 2008–2010 Kristaps Dzonsons, $Date: 2010/06/19 20:43:35 $
1.40 kristaps 435: </DIV>
436: </TD>
437: </TR>
438: </TBODY>
439: </TABLE>
440: </BODY>
441: </HTML>
CVSweb