Annotation of mandoc/index.sgml, Revision 1.118
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: <LINK REL="stylesheet" HREF="index.css" TYPE="text/css" MEDIA="all">
1.47 kristaps 6: <TITLE>mdocml | mdoc macro compiler</TITLE>
1.40 kristaps 7: </HEAD>
8: <BODY>
1.112 kristaps 9: <P CLASS="head">
10: <B>mdocml</B> – mdoc macro compiler
11: </P>
12:
13: <H1>
1.118 ! kristaps 14: <A NAME="description">Description</A>
1.112 kristaps 15: </H1>
16:
17: <P>
18: <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <I><A HREF="mdoc.7.html">mdoc</A></I>, the roff macro
19: package of choice for BSD manual pages, and <I><A HREF="man.7.html">man</A></I>, the predominant historical package for
20: UNIX manuals. The mission of <SPAN CLASS="nm">mdocml</SPAN> is to deprecate <A
21: HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU troff implementation, for displaying <I>mdoc</I>
22: pages whilst providing token support for <I>man</I>.
23: </P>
24:
25: <P>
26: Why? groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL. It runs slowly, produces
27: uncertain output, and varies in operation from system to system. mdocml strives to fix this (respectively small, C, <A
28: CLASS="external" HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
29: </P>
30:
31: <P>
32: <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating compiler and <A
33: HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format output for UNIX terminals, XHTML,
34: HTML, PostScript, and PDF. It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.
35: </P>
36:
37: <P>
38: <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary, <Q>mandoc</Q>.
39: </P>
40:
41: <H1>
1.118 ! kristaps 42: <A NAME="sources">Sources</A>
1.112 kristaps 43: </H1>
44:
45: <P>
1.118 ! kristaps 46: <SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any UNIX system, although <A
! 47: HREF="makewhatis.1.html">makewhatis</A> requires <A CLASS="external"
! 48: HREF="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">Berkeley Database</A> (this is
! 49: installed by default on all BSD operating systems). The most current version is <SPAN CLASS="attn">@VERSION@</SPAN>,
! 50: dated <SPAN class="attn">@VDATE@</SPAN>. If your system doesn't come with <SPAN CLASS="nm">mdocml</SPAN> (see
! 51: <Q>Downstream</Q>), run <CODE>make</CODE> to compile and <CODE>make install</CODE> to install into <I>/usr/local</I>.
1.115 kristaps 52: Note that <A HREF="makewhatis.1.html">makewhatis</A> is not yet linked to the build. You must run <CODE>make
1.118 ! kristaps 53: makewhatis</CODE> to build it (it does not install).
1.112 kristaps 54: </P>
55:
56: <H2>
57: Current
58: </H2>
59:
60: <TABLE WIDTH="100%" SUMMARY="Current Sources">
61: <COL WIDTH="175">
62: <COL>
63: <TBODY>
64: <TR>
65: <TD>Source archive</TD>
66: <TD>
67: <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
68: (<A HREF="/snapshots/mdocml.md5">md5</A>)
69: </TD>
70: </TR>
71: <TR>
72: <TD>Online source</TD>
73: <TD>
74: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
75: </TD>
76: </TR>
77: </TBODY>
78: </TABLE>
79:
80: <H2>
81: Downstream
82: </H2>
83:
84: <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
85: <COL WIDTH="175">
86: <COL>
87: <TBODY>
88: <TR>
89: <TD>DragonFly BSD</TD>
90: <TD>
91: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
92: CLASS="external">usr.bin/mandoc</A>
93: </TD>
94: </TR>
95: <TR>
96: <TD>FreeBSD</TD>
97: <TD>
98: <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
99: CLASS="external">ports/textproc/mdocml</A>
100: </TD>
101: </TR>
102: <TR>
103: <TD>NetBSD</TD>
104: <TD>
105: <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
106: CLASS="external">src/external/bsd/mdocml</A>
107: </TD>
108: </TR>
109: <TR>
110: <TD>OpenBSD</TD>
111: <TD>
112: <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
113: CLASS="external">src/usr.bin/mandoc</A>
114: </TD>
115: </TR>
116: </TBODY>
117: </TABLE>
118:
119: <H2>
120: Historical
121: </H2>
122:
123: <TABLE WIDTH="100%" SUMMARY="Archived Sources">
124: <COL WIDTH="175">
125: <COL>
126: <TBODY>
127: <TR>
128: <TD>Source archive</TD>
129: <TD>
130: <A HREF="/snapshots/">/snapshots/</A>
131: </TD>
132: </TR>
133: </TBODY>
134: </TABLE>
135:
136: <H1>
1.118 ! kristaps 137: <A NAME="documentation">Documentation</A>
1.112 kristaps 138: </H1>
139:
140: <P>
141: These manuals are generated automatically and refer to the current snapshot.
142: </P>
143:
144: <TABLE WIDTH="100%" SUMMARY="Documentation">
145: <COL WIDTH="175">
146: <COL>
147: <TBODY>
148: <TR>
149: <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
150: <TD VALIGN="top">
151: format and display UNIX manuals
152: <SMALL>
153: (<A HREF="mandoc.1.txt">text</A> |
154: <A HREF="mandoc.1.xhtml">xhtml</A> |
155: <A HREF="mandoc.1.pdf">pdf</A> |
156: <A HREF="mandoc.1.ps">postscript</A>)
157: </SMALL>
158: </TD>
159: </TR>
160: <TR>
1.117 kristaps 161: <TD VALIGN="top"><A HREF="makewhatis.1.html">makewhatis(1)</A></TD>
1.114 kristaps 162: <TD VALIGN="top">
163: index UNIX manuals
164: <SMALL>
1.115 kristaps 165: (<A HREF="makewhatis.1.txt">text</A> |
166: <A HREF="makewhatis.1.xhtml">xhtml</A> |
167: <A HREF="makewhatis.1.pdf">pdf</A> |
168: <A HREF="makewhatis.1.ps">postscript</A>)
1.114 kristaps 169: </SMALL>
170: </TD>
171: </TR>
172: <TR>
1.112 kristaps 173: <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
174: <TD VALIGN="top">
175: mandoc macro compiler library
176: <SMALL>
177: (<A HREF="mandoc.3.txt">text</A> |
178: <A HREF="mandoc.3.xhtml">xhtml</A> |
179: <A HREF="mandoc.3.pdf">pdf</A> |
180: <A HREF="mandoc.3.ps">postscript</A>)
181: </SMALL>
182: </TD>
183: </TR>
184: <TR>
185: <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
186: <TD VALIGN="top">
187: man language reference
188: <SMALL>
189: (<A HREF="man.7.txt">text</A> |
190: <A HREF="man.7.xhtml">xhtml</A> |
191: <A HREF="man.7.pdf">pdf</A> |
192: <A HREF="man.7.ps">postscript</A>)
193: </SMALL>
194: </TD>
195: </TR>
196: <TR>
197: <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
198: <TD VALIGN="top">
199: eqn-mandoc language reference
200: <SMALL>
201: (<A HREF="eqn.7.txt">text</A> |
202: <A HREF="eqn.7.xhtml">xhtml</A> |
203: <A HREF="eqn.7.pdf">pdf</A> |
204: <A HREF="eqn.7.ps">postscript</A>)
205: </SMALL>
206: </TD>
207: </TR>
208: <TR>
209: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
210: <TD VALIGN="top">
211: mandoc special characters
212: <SMALL>
213: (<A HREF="mandoc_char.7.txt">text</A> |
214: <A HREF="mandoc_char.7.xhtml">xhtml</A> |
215: <A HREF="mandoc_char.7.pdf">pdf</A> |
216: <A HREF="mandoc_char.7.ps">postscript</A>)
217: </SMALL>
218: </TD>
219: </TR>
220: <TR>
221: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
222: <TD VALIGN="top">
223: mdoc language reference
224: <SMALL>
225: (<A HREF="mdoc.7.txt">text</A> |
226: <A HREF="mdoc.7.xhtml">xhtml</A> |
227: <A HREF="mdoc.7.pdf">pdf</A> |
228: <A HREF="mdoc.7.ps">postscript</A>)
229: </SMALL>
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: <SMALL>
237: (<A HREF="roff.7.txt">text</A> |
238: <A HREF="roff.7.xhtml">xhtml</A> |
239: <A HREF="roff.7.pdf">pdf</A> |
240: <A HREF="roff.7.ps">postscript</A>)
241: </SMALL>
242: </TD>
243: </TR>
244: <TR>
245: <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
246: <TD VALIGN="top">
247: tbl-mandoc language reference
248: <SMALL>
249: (<A HREF="tbl.7.txt">text</A> |
250: <A HREF="tbl.7.xhtml">xhtml</A> |
251: <A HREF="tbl.7.pdf">pdf</A> |
252: <A HREF="tbl.7.ps">postscript</A>)
253: </SMALL>
254: </TD>
255: </TR>
256: </TBODY>
257: </TABLE>
258:
259: <H1>
1.118 ! kristaps 260: <A NAME="contact">Contact</A>
1.112 kristaps 261: </H1>
262:
263: <P>
264: Use the mailing lists for bug-reports, patches, questions, etc. (these require subscription). Please check the
265: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
266: before posting. Beyond that, contact Kristaps at <A
267: HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
268: this e-mail address">kris...</A>@bsd.lv.
269: </P>
270:
271: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
272: <COL WIDTH="175">
273: <COL>
274: <TBODY>
275: <TR>
276: <TD>
277: disc<A CLASS="external" TITLE="Reveal this e-mail address"
278: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
279: </TD>
280: <TD>
281: bug-reports, general questions, and announcements
282: <SMALL>(<A HREF="/archives/discuss/summary.html">archive</A>)</SMALL>
283: </TD>
284: </TR>
285: <TR>
286: <TD>
287: tec<A CLASS="external" TITLE="Reveal this e-mail address"
288: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
289: </TD>
290: <TD>
291: patches and system discussions
292: <SMALL>(<A HREF="/archives/tech/summary.html">archive</A>)</SMALL>
293: </TD>
294: </TR>
295: <TR>
296: <TD>
297: sou<A CLASS="external" TITLE="Reveal this e-mail address"
298: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
299: </TD>
300: <TD>
301: source commit messages
302: <SMALL>(<A HREF="/archives/source/summary.html">archive</A>)</SMALL>
303: </TD>
304: </TR>
305: </TBODY>
306: </TABLE>
307:
308: <H1>
1.118 ! kristaps 309: <A NAME="news">News</A>
1.112 kristaps 310: </H1>
311:
312: <P CLASS="news">
1.115 kristaps 313: 12-05-2011: version 1.11.2
314: </P>
315: <P>
316: Corrected some installation issues in version 1.11.1.
1.116 kristaps 317: Further migration to <A HREF="mandoc.3.html">libmandoc</A>.
1.115 kristaps 318: Initial public release (this utility is very much under development) of <A HREF="makewhatis.1.html">makewhatis</A>,
319: initially named mandoc-db.
320: This utility produces keyword databases of manual content
321: <A HREF="http://mdocml.bsd.lv/mandoc-cgi/index.html">mandoc-cgi</A>, which features semantic querying of manual content.
322: </P>
323:
324: <P CLASS="news">
1.112 kristaps 325: 04-04-2011: version 1.11.1
326: </P>
327: <P>
328: The earlier <I>libroff</I>, <I>libmdoc</I>, and <I>libman</I> soup have been merged into
329: a single library, <A HREF="mandoc.3.html">libmandoc</A>, which manages all aspects of
330: parsing real manuals (from line-handling to <A HREF="tbl.7.html">tbl</A> parsing).
331: </P>
332: <P>
333: Beyond this structural change, initial <A HREF="eqn.7.html">eqn</A> functionality is in
334: place. For the time being, this is limited to the recognition of equation blocks;
335: future version of <SPAN CLASS="nm">mdocml</SPAN> will expand upon this framework.
336: </P>
337: <P>
1.113 kristaps 338: As usual, many general fixes and improvements have also occurred. In particular, a great
1.112 kristaps 339: deal of redundancy and superfluous code has been removed with the merging of the backend
340: libraries.
341: </P>
342:
343: <P>
344: See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
345: historical notes.
346: </P>
347:
348: <P CLASS="foot">
1.118 ! kristaps 349: <SMALL>
! 350: Copyright © 2008–2011
! 351: <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
! 352: $Date: 2011/05/13 01:04:07 $
! 353: </SMALL>
1.112 kristaps 354: </P>
1.40 kristaps 355: </BODY>
356: </HTML>
CVSweb