]> git.cameronkatri.com Git - mandoc.git/blob - index.sgml
Added last version notes and bumped version number and date.
[mandoc.git] / index.sgml
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>
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, PostScript, and PDF. <SPAN CLASS="nm">mdocml</SPAN> is a <A CLASS="external"
46 HREF="http://bsd.lv/">BSD.lv</A> project.
47 </P>
48
49 <P>
50 <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary,
51 <Q>mandoc</Q>.
52 </P>
53 </TD>
54 </TR>
55 <TR>
56 <TD>
57 <H1>
58 <A NAME="sources">SOURCES</A>
59 </H1>
60
61 <P>
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.
65 </P>
66
67 <H2>
68 Current
69 </H2>
70
71 <TABLE WIDTH="100%" SUMMARY="Current Sources">
72 <COL WIDTH="175">
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>
85 <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
86 </TD>
87 </TR>
88 </TBODY>
89 </TABLE>
90
91 <H2>
92 Downstream
93 </H2>
94
95 <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
96 <COL WIDTH="175">
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>
129
130 <H2>
131 Historical
132 </H2>
133
134 <TABLE WIDTH="100%" SUMMARY="Archived Sources">
135 <COL WIDTH="175">
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>
151 <A NAME="documentation">DOCUMENTATION</A>
152 </H1>
153
154 <P>
155 These manuals are generated automatically and refer to the current snapshot.
156 </P>
157
158 <TABLE WIDTH="100%" SUMMARY="Documentation">
159 <COL WIDTH="175">
160 <COL>
161 <TBODY>
162 <TR>
163 <TD VALIGN="top"><A HREF="man.3.html">man(3)</A></TD>
164 <TD VALIGN="top">
165 man macro compiler library
166 <SPAN STYLE="font-size: smaller;">
167 (<A HREF="man.3.txt">text</A> |
168 <A HREF="man.3.xhtml">xhtml</A> |
169 <A HREF="man.3.pdf">pdf</A> |
170 <A HREF="man.3.ps">postscript</A>)
171 </SPAN>
172 </TD>
173 </TR>
174 <TR>
175 <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
176 <TD VALIGN="top">
177 man language reference
178 <SPAN STYLE="font-size: smaller;">
179 (<A HREF="man.7.txt">text</A> |
180 <A HREF="man.7.xhtml">xhtml</A> |
181 <A HREF="man.7.pdf">pdf</A> |
182 <A HREF="man.7.ps">postscript</A>)
183 </SPAN>
184 </TD>
185 </TR>
186 <TR>
187 <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
188 <TD VALIGN="top">
189 format and display UNIX manuals
190 <SPAN STYLE="font-size: smaller;">
191 (<A HREF="mandoc.1.txt">text</A> |
192 <A HREF="mandoc.1.xhtml">xhtml</A> |
193 <A HREF="mandoc.1.pdf">pdf</A> |
194 <A HREF="mandoc.1.ps">postscript</A>)
195 </SPAN>
196 </TD>
197 </TR>
198 <TR>
199 <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
200 <TD VALIGN="top">
201 mandoc special characters
202 <SPAN STYLE="font-size: smaller;">
203 (<A HREF="mandoc_char.7.txt">text</A> |
204 <A HREF="mandoc_char.7.xhtml">xhtml</A> |
205 <A HREF="mandoc_char.7.pdf">pdf</A> |
206 <A HREF="mandoc_char.7.ps">postscript</A>)
207 </SPAN>
208 </TD>
209 </TR>
210 <TR>
211 <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
212 <TD VALIGN="top">
213 mdoc macro compiler library
214 <SPAN STYLE="font-size: smaller;">
215 (<A HREF="mdoc.3.txt">text</A> |
216 <A HREF="mdoc.3.xhtml">xhtml</A> |
217 <A HREF="mdoc.3.pdf">pdf</A> |
218 <A HREF="mdoc.3.ps">postscript</A>)
219 </SPAN>
220 </TD>
221 </TR>
222 <TR>
223 <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
224 <TD VALIGN="top">
225 mdoc language reference
226 <SPAN STYLE="font-size: smaller;">
227 (<A HREF="mdoc.7.txt">text</A> |
228 <A HREF="mdoc.7.xhtml">xhtml</A> |
229 <A HREF="mdoc.7.pdf">pdf</A> |
230 <A HREF="mdoc.7.ps">postscript</A>)
231 </SPAN>
232 </TD>
233 </TR>
234 <TR>
235 <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
236 <TD VALIGN="top">
237 roff macro compiler library
238 <SPAN STYLE="font-size: smaller;">
239 (<A HREF="roff.3.txt">text</A> |
240 <A HREF="roff.3.xhtml">xhtml</A> |
241 <A HREF="roff.3.pdf">pdf</A> |
242 <A HREF="roff.3.ps">postscript</A>)
243 </SPAN>
244 </TD>
245 </TR>
246 <TR>
247 <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
248 <TD VALIGN="top">
249 roff-mandoc language reference
250 <SPAN STYLE="font-size: smaller;">
251 (<A HREF="roff.7.txt">text</A> |
252 <A HREF="roff.7.xhtml">xhtml</A> |
253 <A HREF="roff.7.pdf">pdf</A> |
254 <A HREF="roff.7.ps">postscript</A>)
255 </SPAN>
256 </TD>
257 </TR>
258 </TBODY>
259 </TABLE>
260
261 <P>
262 See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
263 introduction to manpages and mdoc.
264 </P>
265 </TD>
266 </TR>
267 <TR>
268 <TD>
269 <H1>
270 <A NAME="contact">CONTACT</A>
271 </H1>
272
273 <P>
274 Please use the mailing lists for bug-reports, patches, questions, etc. Beyond that, contact
275 Kristaps at <A
276 HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q=="
277 TITLE="Reveal this e-mail address">kris...</A>@bsd.lv.
278 </P>
279
280 <P>
281 You may also subscribe to several mailing lists (these require subscription, which is
282 moderated).
283 </P>
284
285 <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
286 <COL WIDTH="175">
287 <COL>
288 <TBODY>
289 <TR>
290 <TD>
291 disc<A CLASS="external" TITLE="Reveal this e-mail address"
292 HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
293 </TD>
294 <TD>
295 bug-reports, general questions, and announcements
296 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/discuss/summary.html">archive</A>)</SPAN>
297 </TD>
298 </TR>
299 <TR>
300 <TD>
301 tec<A CLASS="external" TITLE="Reveal this e-mail address"
302 HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&amp;c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
303 </TD>
304 <TD>
305 patches and system discussions
306 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/tech/summary.html">archive</A>)</SPAN>
307 </TD>
308 </TR>
309 <TR>
310 <TD>
311 sou<A CLASS="external" TITLE="Reveal this e-mail address"
312 HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
313 </TD>
314 <TD>
315 source commit messages
316 <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/source/summary.html">archive</A>)</SPAN>
317 </TD>
318 </TR>
319 </TBODY>
320 </TABLE>
321 </TD>
322 </TR>
323 <TR>
324 <TD>
325 <H1>
326 <A NAME="news">NEWS</A>
327 </H1>
328 <DIV CLASS="news">
329 <P>
330 <SPAN CLASS="date">23-12-2010</SPAN>:
331 version 1.10.8
332 </P>
333 <P>
334 Significant improvements merged from <A CLASS="external"
335 HREF="http://www.openbsd.org">OpenBSD</A> downstream, including
336 </P>
337 <UL>
338 <LI>many new <A HREF="roff.7.html">roff</A> components,</LI>
339 <LI>in-line implementation of troff's soelim,</LI>
340 <LI>broken-block handling,</LI>
341 <LI>overhauled error classifications, and</LI>
342 <LI>cleaned up handling of error conditions.</LI>
343 </UL>
344 <P>
345 Also overhauled the <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
346 CLASS="flag">-Txhtml</SPAN> output modes. They now display readable output in arbitrary
347 browsers, including text-based ones like <A CLASS="external"
348 HREF="http://lynx.isc.org">lynx</A>. See HTML and XHTML manuals in the <A
349 HREF="#documentation">DOCUMENTATION</A> section for examples. <SPAN
350 CLASS="attn">Attention: available style-sheet classes have been considerably
351 changed!</SPAN> See the <SPAN CLASS="file">example.style.css</SPAN> file for details.
352 Lastly, <A HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> have been
353 cleaned up and reduced in size and complexity.
354 </P>
355 </DIV>
356 <DIV CLASS="news">
357 <P>
358 <SPAN CLASS="date">27-09-2010</SPAN>:
359 version 1.10.6
360 </P>
361 <P>
362 Calling conventions for <A HREF="mandoc.1.html">mandoc</A> have changed: <SPAN
363 CLASS="flag">-W</SPAN> improved and <SPAN CLASS="flag">-f</SPAN> deprecated. Non-ASCII
364 characters are also now uniformly discarded. Lots of documentation improvements. Many
365 incremental fixes accomodating for groff's more interesting productions. Lastly, <A
366 HREF="http://perldoc.perl.org/pod2man.html" CLASS="external">pod2man</A> preambles are
367 now fully accepted after some considerable <A HREF="roff.7.html">roff</A> and special
368 character support.
369 </P>
370 </DIV>
371 <DIV CLASS="news">
372 <P>
373 <SPAN CLASS="date">27-07-2010</SPAN>:
374 version 1.10.5
375 </P>
376 <P>
377 Primarily a bug-fix and polish release, but including <SPAN CLASS="flag">-Tpdf</SPAN>
378 support in <A HREF="mandoc.1.html">mandoc</A> by way of <A CLASS="external"
379 HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">Summer of Code</A>.
380 Highlights:
381 </P>
382 <UL>
383 <LI>fix <Q>Sm</Q> and <Q>Bd</Q> handling</LI>
384 <LI>fix end-of-sentence handling for embedded sentences</LI>
385 <LI>polish <A HREF="man.7.html">man</A> documentation</LI>
386 <LI>document all <A HREF="mdoc.7.html">mdoc</A> macros</LI>
387 <LI>polish <A HREF="mandoc.1.html">mandoc</A> <SPAN CLASS="flag">-Tps</SPAN> output</LI>
388 <LI>lots of internal clean-ups in character escapes</LI>
389 <LI>un-break literal contexts in <A HREF="man.7.html">man</A> documents</LI>
390 <LI>improve <SPAN CLASS="flag">-Thtml</SPAN> output for <SPAN CLASS="flag">-man</SPAN></LI>
391 <LI>add <A HREF="mandoc.1.html">mandoc</A> <SPAN CLASS="flag">-Tpdf</SPAN> support</LI>
392 </UL>
393 </DIV>
394 <DIV CLASS="news">
395 <P>
396 <SPAN CLASS="date">12-07-2010</SPAN>:
397 version 1.10.4
398 </P>
399 <P>
400 Lots of features developed during both <A CLASS="external"
401 HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">Summer of Code</A> and the
402 <A CLASS="external" HREF="http://www.openbsd.org">OpenBSD</A> c2k10 hackathon:
403 </P>
404 <UL>
405 <LI>minimal <Q>ds</Q> <A HREF="roff.7.html">roff</A> symbols are supported</LI>
406 <LI><Q>Bk</Q> <A HREF="mdoc.7.html">mdoc</A> support</LI>
407 <LI>beautified SYNOPSIS section output</LI>
408 <LI>variable font-width and paper-size support in <A HREF="mandoc.1.html">mandoc</A>
409 <SPAN CLASS="flag">-Tps</SPAN> output</LI>
410 <LI>acceptance of scope-block breakage in <A HREF="mdoc.7.html">mdoc</A></LI>
411 <LI>clarify error message status</LI>
412 <LI>many minor bug-fixes and formatting issues resolved</LI>
413 </UL>
414 </DIV>
415 <DIV CLASS="news">
416 <P>
417 <SPAN CLASS="date">19-06-2010</SPAN>:
418 version 1.10.2
419 </P>
420 <P>
421 Small release featuring text-decoration in <SPAN CLASS="flag">-Tps</SPAN> output, a few
422 minor relaxations of errors, and some optimisations.
423 </P>
424 </DIV>
425 <DIV CLASS="news">
426 <P>
427 <SPAN CLASS="date">07-06-2010</SPAN>:
428 version 1.10.1
429 </P>
430 <P>
431 This primarily focusses on the <Q>Bl</Q> and <Q>It</Q> macros described in <A
432 HREF="mdoc.7.html">mdoc</A>. Multi-line column support is now fully compatible with
433 groff, as are implicit list entries for columns. Removed manuals.7 in favour of <A
434 CLASS="external" HREF="http://manpages.bsd.lv">http://manpages.bsd.lv</A>. The way we
435 handle the SYNOPSIS section (see the SYNOPSIS documentation in <A
436 HREF="mdoc.7.html#x4d414e55414cx20x535452554354555245">MANUAL STRUCTURE</A>) has also
437 been considerably simplified compared to groff's method. Furthermore, the <SPAN
438 CLASS="flag">-Owidth=width</SPAN> output option has been added to <SPAN
439 CLASS="flag">-Tascii</SPAN> (see <A HREF="mandoc.1.html">mandoc</A>). Lastly, initial
440 PostScript output has been added with the <SPAN CLASS="flag">-Tps</SPAN> option to <A
441 HREF="mandoc.1.html">mandoc</A>. It's brutally simple at the moment: fixed-font, with
442 no font decorations.
443 </P>
444 </DIV>
445 <DIV CLASS="news">
446 <P>
447 <SPAN CLASS="date">29-05-2010</SPAN>:
448 version 1.10.0
449 </P>
450 <P>
451 Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD.
452 This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg
453 Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10.
454 Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:
455 </P>
456 <UL>
457 <LI>a <A HREF="roff.3.html">libroff</A> preprocessor in front of <A
458 HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> stripping out
459 <A HREF="roff.7.html">roff</A> instructions;</LI>
460 <LI>end-of-sentence (EOS) detection in free-form and macro lines;</LI>
461 <LI>correct handling of tab-separated columnar lists in <SPAN
462 CLASS="flag">-mdoc</SPAN>;</LI>
463 <LI>improved main calling routines to optionally use mmap() for better
464 performance;</LI>
465 <LI>cleaned up exiting when invoked as <SPAN CLASS="flag">-Tlint</SPAN> or over
466 multiple files with <SPAN CLASS="flag">-fign-errors</SPAN>;</LI>
467 <LI>error and warning message handling re-written to be unified for <A
468 HREF="roff.3.html">libroff</A>, <A HREF="mdoc.3.html">libmdoc</A>, and <A
469 HREF="man.3.html">libman</A>;</LI>
470 <LI>handling of badly-nested explicit-scoped macros;</LI>
471 <LI>improved free-form text parsing in <A HREF="man.3.html">libman</A> and <A
472 HREF="mdoc.3.html">libmdoc</A>;</LI>
473 <LI>significant GNU troff compatibility improvements in <SPAN
474 CLASS="flag">-Tascii</SPAN>, largely in terms of spacing;</LI>
475 <LI>a regression framework for making sure the many fragilities of GNU troff
476 aren't trampled in subsequent work;</LI>
477 <LI>support for <SPAN CLASS="flag">-Tascii</SPAN> breaking at hyphens
478 encountered in free-form text;</LI>
479 <LI>and many more minor fixes and improvements (no really, consult <A
480 HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> and see
481 for yourself!).</LI>
482 </UL>
483 </DIV>
484 <P>
485 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
486 historical notes.
487 </P>
488 </TD>
489 </TR>
490 <TR>
491 <TD>
492 <DIV CLASS="foot">
493 Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2010/12/23 00:30:20 $
494 </DIV>
495 </TD>
496 </TR>
497 </TBODY>
498 </TABLE>
499 </BODY>
500 </HTML>