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