Import mdocml-1.11.1
[dragonfly.git] / contrib / mdocml / index.sgml
CommitLineData
80387638
SW
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
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">
7 <TITLE>mdocml | mdoc macro compiler</TITLE>
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> &#8211; mdoc macro compiler
17 </DIV>
18 </TD>
19 </TR>
20 <TR>
21 <TD VALIGN="top">
22 <H1>
23 <A NAME="description">DESCRIPTION</A>
24 </H1>
25
26 <P>
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.
32 </P>
33
34 <P>
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
37 this (respectively small, C, <A CLASS="external"
38 HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
39 </P>
40
41 <P>
60e1e752
SW
42 <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating
43 compiler and <A HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format
44 output for UNIX terminals, XHTML, HTML, PostScript, and PDF. It is a <A CLASS="external"
80387638
SW
45 HREF="http://bsd.lv/">BSD.lv</A> project.
46 </P>
47
48 <P>
49 <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary,
50 <Q>mandoc</Q>.
51 </P>
52 </TD>
53 </TR>
54 <TR>
55 <TD>
56 <H1>
57 <A NAME="sources">SOURCES</A>
58 </H1>
59
60 <P>
60e1e752
SW
61 <SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any UNIX system.
62 The most current version is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>.
80387638
SW
63 </P>
64
65 <H2>
66 Current
67 </H2>
68
69 <TABLE WIDTH="100%" SUMMARY="Current Sources">
70 <COL WIDTH="175">
71 <COL>
72 <TBODY>
73 <TR>
74 <TD>Source archive</TD>
75 <TD>
76 <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
77 (<A HREF="/snapshots/mdocml.md5">md5</A>)
78 </TD>
79 </TR>
80 <TR>
81 <TD>Online source</TD>
82 <TD>
83 <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
84 </TD>
85 </TR>
86 </TBODY>
87 </TABLE>
88
89 <H2>
90 Downstream
91 </H2>
92
93 <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
94 <COL WIDTH="175">
95 <COL>
96 <TBODY>
97 <TR>
98 <TD>DragonFly BSD</TD>
99 <TD>
100 <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
101 CLASS="external">usr.bin/mandoc</A>
102 </TD>
103 </TR>
104 <TR>
105 <TD>FreeBSD</TD>
106 <TD>
107 <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
108 CLASS="external">ports/textproc/mdocml</A>
109 </TD>
110 </TR>
111 <TR>
112 <TD>NetBSD</TD>
113 <TD>
114 <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
115 CLASS="external">src/external/bsd/mdocml</A>
116 </TD>
117 </TR>
118 <TR>
119 <TD>OpenBSD</TD>
120 <TD>
121 <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
122 CLASS="external">src/usr.bin/mandoc</A>
123 </TD>
124 </TR>
125 </TBODY>
126 </TABLE>
127
128 <H2>
129 Historical
130 </H2>
131
132 <TABLE WIDTH="100%" SUMMARY="Archived Sources">
133 <COL WIDTH="175">
134 <COL>
135 <TBODY>
136 <TR>
137 <TD>Source archive</TD>
138 <TD>
139 <A HREF="/snapshots/">/snapshots/</A>
140 </TD>
141 </TR>
142 </TBODY>
143 </TABLE>
144 </TD>
145 </TR>
146 <TR>
147 <TD>
148 <H1>
149 <A NAME="documentation">DOCUMENTATION</A>
150 </H1>
151
152 <P>
153 These manuals are generated automatically and refer to the current snapshot.
154 </P>
155
156 <TABLE WIDTH="100%" SUMMARY="Documentation">
157 <COL WIDTH="175">
158 <COL>
159 <TBODY>
160 <TR>
161 <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
162 <TD VALIGN="top">
163 format and display UNIX manuals
164 <SPAN STYLE="font-size: smaller;">
165 (<A HREF="mandoc.1.txt">text</A> |
166 <A HREF="mandoc.1.xhtml">xhtml</A> |
167 <A HREF="mandoc.1.pdf">pdf</A> |
168 <A HREF="mandoc.1.ps">postscript</A>)
169 </SPAN>
170 </TD>
171 </TR>
172 <TR>
60e1e752 173 <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
80387638 174 <TD VALIGN="top">
60e1e752 175 mandoc macro compiler library
80387638 176 <SPAN STYLE="font-size: smaller;">
60e1e752
SW
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>)
80387638
SW
181 </SPAN>
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 <SPAN STYLE="font-size: smaller;">
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 </SPAN>
194 </TD>
195 </TR>
60e1e752
SW
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 <SPAN STYLE="font-size: smaller;">
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 </SPAN>
206 </TD>
207 </TR>
80387638
SW
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 <SPAN STYLE="font-size: smaller;">
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 </SPAN>
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 <SPAN STYLE="font-size: smaller;">
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 </SPAN>
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 <SPAN STYLE="font-size: smaller;">
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 </SPAN>
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 <SPAN STYLE="font-size: smaller;">
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 </SPAN>
254 </TD>
255 </TR>
256 </TBODY>
257 </TABLE>
258
259 <P>
260 See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
261 introduction to manpages and mdoc.
262 </P>
263 </TD>
264 </TR>
265 <TR>
266 <TD>
267 <H1>
268 <A NAME="contact">CONTACT</A>
269 </H1>
270
271 <P>
60e1e752
SW
272 Use the mailing lists for bug-reports, patches, questions, etc. (these require
273 subscription).
274 Please check the
275 <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
276 before posting.
277 Beyond that, contact Kristaps at <A
80387638
SW
278 HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q=="
279 TITLE="Reveal this e-mail address">kris...</A>@bsd.lv.
280 </P>
281
282 <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
283 <COL WIDTH="175">
284 <COL>
285 <TBODY>
286 <TR>
287 <TD>
288 disc<A CLASS="external" TITLE="Reveal this e-mail address"
289 HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
290 </TD>
291 <TD>
292 bug-reports, general questions, and announcements
293 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/discuss/summary.html">archive</A>)</SPAN>
294 </TD>
295 </TR>
296 <TR>
297 <TD>
298 tec<A CLASS="external" TITLE="Reveal this e-mail address"
299 HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&amp;c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
300 </TD>
301 <TD>
302 patches and system discussions
303 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/tech/summary.html">archive</A>)</SPAN>
304 </TD>
305 </TR>
306 <TR>
307 <TD>
308 sou<A CLASS="external" TITLE="Reveal this e-mail address"
309 HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
310 </TD>
311 <TD>
312 source commit messages
313 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/source/summary.html">archive</A>)</SPAN>
314 </TD>
315 </TR>
316 </TBODY>
317 </TABLE>
318 </TD>
319 </TR>
320 <TR>
321 <TD>
322 <H1>
323 <A NAME="news">NEWS</A>
324 </H1>
60e1e752
SW
325 <DIV CLASS="news">
326 <P>
327 <SPAN CLASS="date">04-04-2011</SPAN>:
328 version 1.11.1
329 </P>
330 <P>
331 The earlier <I>libroff</I>, <I>libmdoc</I>, and <I>libman</I> soup have been merged into
332 a single library, <A HREF="mandoc.3.html">libmandoc</A>, which manages all aspects of
333 parsing real manuals (from line-handling to <A HREF="tbl.7.html">tbl</A> parsing).
334 </P>
335 <P>
336 Beyond this structural change, initial <A HREF="eqn.7.html">eqn</A> functionality is in
337 place. For the time being, this is limited to the recognition of equation blocks;
338 future version of <SPAN CLASS="nm">mdocml</SPAN> will expand upon this framework.
339 </P>
340 <P>
341 As usual, many general fixes and improvements have also occured. In particular, a great
342 deal of redundancy and superfluous code has been removed with the merging of the backend
343 libraries.
344 </P>
345 </DIV>
80387638
SW
346 <DIV CLASS="news">
347 <P>
348 <SPAN CLASS="date">07-01-2011</SPAN>:
349 version 1.10.9
350 </P>
351 <P>
352 Many back-end fixes have been implemented: argument handling (quoting), <A
353 HREF="man.7.html">man</A> improvements, error/warning classes, and many more.
354 </P>
355 <P>
356 Initial <A HREF="tbl.7.html">tbl</A> functionality (see the <Q>TS</Q>, <Q>TE</Q>, and
357 <Q>T&amp;</Q> macros in the <A HREF="roff.7.html#x5c265453">roff</A> manual) has been
358 merged from <A CLASS="external" HREF="http://tbl.bsd.lv">tbl.bsd.lv</A>. Output is
359 still minimal, especially for <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
360 CLASS="flag">-Txhtml</SPAN>, but manages to at least display data. This means that <A
361 HREF="mandoc.1.html">mandoc</A> now has built-in support for two troff preprocessors via
60e1e752 362 <DEL>libroff</DEL>: soelim and tbl.
80387638
SW
363 </P>
364 </DIV>
365 <DIV CLASS="news">
366 <P>
367 <SPAN CLASS="date">24-12-2010</SPAN>:
368 version 1.10.8
369 </P>
370 <P>
371 Significant improvements merged from <A CLASS="external"
372 HREF="http://www.openbsd.org">OpenBSD</A> downstream, including
373 </P>
374 <UL>
375 <LI>many new <A HREF="roff.7.html">roff</A> components,</LI>
376 <LI>in-line implementation of troff's soelim,</LI>
377 <LI>broken-block handling,</LI>
378 <LI>overhauled error classifications, and</LI>
379 <LI>cleaned up handling of error conditions.</LI>
380 </UL>
381 <P>
382 Also overhauled the <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
383 CLASS="flag">-Txhtml</SPAN> output modes. They now display readable output in arbitrary
384 browsers, including text-based ones like <A CLASS="external"
385 HREF="http://lynx.isc.org">lynx</A>. See HTML and XHTML manuals in the <A
386 HREF="#documentation">DOCUMENTATION</A> section for examples. <SPAN
387 CLASS="attn">Attention: available style-sheet classes have been considerably
388 changed!</SPAN> See the <SPAN CLASS="file">example.style.css</SPAN> file for details.
60e1e752 389 Lastly, <DEL>libmdoc</DEL> and <DEL>libman</DEL> have been
80387638
SW
390 cleaned up and reduced in size and complexity.
391 </P>
392 </DIV>
393 <P>
394 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
395 historical notes.
396 </P>
397 </TD>
398 </TR>
399 <TR>
400 <TD>
401 <DIV CLASS="foot">
60e1e752 402 Copyright &#169; 2008&#8211;2011 Kristaps Dzonsons, $Date: 2011/04/04 21:07:20 $
80387638
SW
403 </DIV>
404 </TD>
405 </TR>
406 </TBODY>
407 </TABLE>
408 </BODY>
409</HTML>