Annotation of mandoc/index.sgml, Revision 1.84
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;">
! 167: (<A HREF="man.3.txt">text</A> | <A HREF="man.3.ps">postscript</A>)
! 168: </SPAN>
1.80 kristaps 169: </TD>
170: </TR>
171: <TR>
172: <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
173: <TD VALIGN="top">
174: man language reference
1.84 ! kristaps 175: <SPAN STYLE="font-size: smaller;">
! 176: (<A HREF="man.7.txt">text</A> | <A HREF="man.7.ps">postscript</A>)
! 177: </SPAN>
1.80 kristaps 178: </TD>
179: </TR>
180: <TR>
181: <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
182: <TD VALIGN="top">
183: format and display UNIX manuals
1.84 ! kristaps 184: <SPAN STYLE="font-size: smaller;">
! 185: (<A HREF="mandoc.1.txt">text</A> | <A HREF="mandoc.1.ps">postscript</A>)
! 186: </SPAN>
1.80 kristaps 187: </TD>
188: </TR>
189: <TR>
190: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
191: <TD VALIGN="top">
192: mandoc special characters
1.84 ! kristaps 193: <SPAN STYLE="font-size: smaller;">
! 194: (<A HREF="mandoc_char.7.txt">text</A> | <A
! 195: HREF="mandoc_char.7.ps">postscript</A>)
! 196: </SPAN>
1.80 kristaps 197: </TD>
198: </TR>
199: <TR>
200: <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
201: <TD VALIGN="top">
202: mdoc macro compiler library
1.84 ! kristaps 203: <SPAN STYLE="font-size: smaller;">
! 204: (<A HREF="mdoc.3.txt">text</A> | <A HREF="mdoc.3.ps">postscript</A>)
! 205: </SPAN>
1.80 kristaps 206: </TD>
207: </TR>
208: <TR>
209: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
210: <TD VALIGN="top">
211: mdoc language reference
1.84 ! kristaps 212: <SPAN STYLE="font-size: smaller;">
! 213: (<A HREF="mdoc.7.txt">text</A> | <A HREF="mdoc.7.ps">postscript</A>)
! 214: </SPAN>
1.80 kristaps 215: </TD>
216: </TR>
217: <TR>
218: <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
219: <TD VALIGN="top">
220: roff macro compiler library
1.84 ! kristaps 221: <SPAN STYLE="font-size: smaller;">
! 222: (<A HREF="roff.3.txt">text</A> | <A HREF="roff.3.ps">postscript</A>)
! 223: </SPAN>
1.80 kristaps 224: </TD>
225: </TR>
226: <TR>
227: <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
228: <TD VALIGN="top">
229: roff-mandoc language reference
1.84 ! kristaps 230: <SPAN STYLE="font-size: smaller;">
! 231: (<A HREF="roff.7.txt">text</A> | <A HREF="roff.7.ps">postscript</A>)
! 232: </SPAN>
1.80 kristaps 233: </TD>
1.71 kristaps 234: </TR>
1.40 kristaps 235: </TBODY>
236: </TABLE>
1.79 kristaps 237:
238: <P>
239: See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
240: introduction to manpages and mdoc.
1.82 kristaps 241: </P>
1.40 kristaps 242: </TD>
243: </TR>
244: <TR>
245: <TD>
246: <H1>
1.75 kristaps 247: <A NAME="contact">CONTACT</A>
1.40 kristaps 248: </H1>
1.1 kristaps 249:
1.40 kristaps 250: <P>
1.84 ! kristaps 251: Please use the mailing lists for bug-reports, patches, questions, etc. Beyond that, contact
! 252: Kristaps at <A
! 253: HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q=="
! 254: TITLE="Reveal this e-mail address">kris...</A>@bsd.lv.
1.40 kristaps 255: </P>
1.18 kristaps 256:
1.40 kristaps 257: <P>
1.84 ! kristaps 258: You may also subscribe to several mailing lists (these require subscription, which is
! 259: moderated). An archive is not yet available on-line, although you may request one once
! 260: subscribed.
1.40 kristaps 261: </P>
1.57 kristaps 262:
263: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
264: <COL WIDTH="200">
265: <COL>
266: <TBODY>
267: <TR>
268: <TD>
1.60 kristaps 269: disc<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 270: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
1.57 kristaps 271: </TD>
1.72 kristaps 272: <TD>high-level discussions and version announcements</TD>
273: </TR>
274: <TR>
275: <TD>
276: tec<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 277: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
1.72 kristaps 278: </TD>
279: <TD>low-level discussions</TD>
1.58 kristaps 280: </TR>
1.67 kristaps 281: <TR>
1.58 kristaps 282: <TD>
283: sou<A CLASS="external" TITLE="Reveal this e-mail address"
1.76 kristaps 284: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
1.58 kristaps 285: </TD>
1.59 kristaps 286: <TD>source commit messages</TD>
1.67 kristaps 287: </TR>
1.57 kristaps 288: </TBODY>
289: </TABLE>
1.40 kristaps 290: </TD>
291: </TR>
292: <TR>
293: <TD>
294: <H1>
1.75 kristaps 295: <A NAME="news">NEWS</A>
1.40 kristaps 296: </H1>
1.77 kristaps 297: <DIV CLASS="news">
298: <P>
1.83 kristaps 299: <SPAN CLASS="date">12-07-2010</SPAN>:
300: version 1.10.4
301: </P>
302: <P>
303: Lots of features developed during both <A CLASS="external"
304: HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">Summer of Code</A> and the
305: <A CLASS="external" HREF="http://www.openbsd.org">OpenBSD</A> c2k10 hackathon:
306: </P>
307: <UL>
308: <LI>minimal <Q>ds</Q> <A HREF="roff.7.html">roff</A> symbols are supported</LI>
309: <LI><Q>Bk</Q> <A HREF="mdoc.7.html">mdoc</A> support</LI>
310: <LI>beautified SYNOPSIS section output</LI>
311: <LI>variable font-width and paper-size support in <A HREF="mandoc.1.html">mandoc</A>
312: -Tps output</LI>
313: <LI>acceptance of scope-block breakage in <A HREF="mdoc.7.html">mdoc</A></LI>
314: <LI>clarify error message status</LI>
315: <LI>many minor bug-fixes and formatting issues resolved</LI>
316: </UL>
317: </DIV>
318: <DIV CLASS="news">
319: <P>
1.82 kristaps 320: <SPAN CLASS="date">19-06-2010</SPAN>:
321: version 1.10.2
322: </P>
323: <P>
324: Small release featuring text-decoration in <SPAN CLASS="flag">-Tps</SPAN> output, a few
325: minor relaxations of errors, and some optimisations.
326: </P>
327: </DIV>
328: <DIV CLASS="news">
329: <P>
1.79 kristaps 330: <SPAN CLASS="date">07-06-2010</SPAN>:
1.77 kristaps 331: version 1.10.1
332: </P>
333: <P>
334: This primarily focusses on the <Q>Bl</Q> and <Q>It</Q> macros described in <A
335: HREF="mdoc.7.html">mdoc</A>. Multi-line column support is now fully compatible with
1.78 kristaps 336: groff, as are implicit list entries for columns. Removed manuals.7 in favour of <A
1.79 kristaps 337: CLASS="external" HREF="http://manpages.bsd.lv">http://manpages.bsd.lv</A>. The way we
338: handle the SYNOPSIS section (see the SYNOPSIS documentation in <A
339: HREF="mdoc.7.html#x4d414e55414cx20x535452554354555245">MANUAL STRUCTURE</A>) has also
1.80 kristaps 340: been considerably simplified compared to groff's method. Furthermore, the <SPAN
1.79 kristaps 341: CLASS="flag">-Owidth=width</SPAN> output option has been added to <SPAN
1.80 kristaps 342: CLASS="flag">-Tascii</SPAN> (see <A HREF="mandoc.1.html">mandoc</A>). Lastly, initial
343: PostScript output has been added with the <SPAN CLASS="flag">-Tps</SPAN> option to <A
344: HREF="mandoc.1.html">mandoc</A>. It's brutally simple at the moment: fixed-font, with
345: no font decorations.
1.77 kristaps 346: </P>
347: </DIV>
1.75 kristaps 348: <DIV CLASS="news">
349: <P>
350: <SPAN CLASS="date">29-05-2010</SPAN>:
351: version 1.10.0
352: </P>
353: <P>
354: Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD.
355: This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg
356: Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10.
357: Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:
358: </P>
359: <UL>
360: <LI>a <A HREF="roff.3.html">libroff</A> preprocessor in front of <A
361: HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> stripping out
362: <A HREF="roff.7.html">roff</A> instructions;</LI>
363: <LI>end-of-sentence (EOS) detection in free-form and macro lines;</LI>
364: <LI>correct handling of tab-separated columnar lists in <SPAN
365: CLASS="flag">-mdoc</SPAN>;</LI>
366: <LI>improved main calling routines to optionally use mmap() for better
367: performance;</LI>
368: <LI>cleaned up exiting when invoked as <SPAN CLASS="flag">-Tlint</SPAN> or over
369: multiple files with <SPAN CLASS="flag">-fign-errors</SPAN>;</LI>
370: <LI>error and warning message handling re-written to be unified for <A
371: HREF="roff.3.html">libroff</A>, <A HREF="mdoc.3.html">libmdoc</A>, and <A
372: HREF="man.3.html">libman</A>;</LI>
373: <LI>handling of badly-nested explicit-scoped macros;</LI>
374: <LI>improved free-form text parsing in <A HREF="man.3.html">libman</A> and <A
375: HREF="mdoc.3.html">libmdoc</A>;</LI>
376: <LI>significant GNU troff compatibility improvements in <SPAN
377: CLASS="flag">-Tascii</SPAN>, largely in terms of spacing;</LI>
378: <LI>a regression framework for making sure the many fragilities of GNU troff
379: aren't trampled in subsequent work;</LI>
380: <LI>support for <SPAN CLASS="flag">-Tascii</SPAN> breaking at hyphens
381: encountered in free-form text;</LI>
382: <LI>and many more minor fixes and improvements (no really, consult <A
383: HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> and see
384: for yourself!).</LI>
385: </UL>
386: </DIV>
387: <P>
388: See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
389: historical notes.
390: </P>
1.40 kristaps 391: </TD>
392: </TR>
393: <TR>
394: <TD>
395: <DIV CLASS="foot">
1.84 ! kristaps 396: Copyright © 2008–2010 Kristaps Dzonsons, $Date: 2010/07/11 23:07:47 $
1.40 kristaps 397: </DIV>
398: </TD>
399: </TR>
400: </TBODY>
401: </TABLE>
402: </BODY>
403: </HTML>
CVSweb