7abc9975f21035a311b44e9f36aa7712e9a24e76
[dragonfly.git] / contrib / mdocml / 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.  It 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="mandoc.1.html">mandoc(1)</A></TD>
164                                                         <TD VALIGN="top">
165                                                                 format and display UNIX manuals
166                                                                 <SPAN STYLE="font-size: smaller;">
167                                                                         (<A HREF="mandoc.1.txt">text</A> | 
168                                                                         <A HREF="mandoc.1.xhtml">xhtml</A> |
169                                                                         <A HREF="mandoc.1.pdf">pdf</A> |
170                                                                         <A HREF="mandoc.1.ps">postscript</A>)
171                                                                 </SPAN>
172                                                         </TD>
173                                                 </TR>
174                                                 <TR>
175                                                         <TD VALIGN="top"><A HREF="man.3.html">man(3)</A></TD>
176                                                         <TD VALIGN="top">
177                                                                 man macro compiler library
178                                                                 <SPAN STYLE="font-size: smaller;">
179                                                                         (<A HREF="man.3.txt">text</A> | 
180                                                                         <A HREF="man.3.xhtml">xhtml</A> |
181                                                                         <A HREF="man.3.pdf">pdf</A> |
182                                                                         <A HREF="man.3.ps">postscript</A>)
183                                                                 </SPAN>
184                                                         </TD>
185                                                 </TR>
186                                                 <TR>
187                                                         <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
188                                                         <TD VALIGN="top">
189                                                                 mdoc macro compiler library
190                                                                 <SPAN STYLE="font-size: smaller;">
191                                                                         (<A HREF="mdoc.3.txt">text</A> | 
192                                                                         <A HREF="mdoc.3.xhtml">xhtml</A> |
193                                                                         <A HREF="mdoc.3.pdf">pdf</A> |
194                                                                         <A HREF="mdoc.3.ps">postscript</A>)
195                                                                 </SPAN>
196                                                         </TD>
197                                                 </TR>
198                                                 <TR>
199                                                         <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
200                                                         <TD VALIGN="top">
201                                                                 roff macro compiler library
202                                                                 <SPAN STYLE="font-size: smaller;">
203                                                                         (<A HREF="roff.3.txt">text</A> | 
204                                                                         <A HREF="roff.3.xhtml">xhtml</A> |
205                                                                         <A HREF="roff.3.pdf">pdf</A> |
206                                                                         <A HREF="roff.3.ps">postscript</A>)
207                                                                 </SPAN>
208                                                         </TD>
209                                                 </TR>
210                                                 <TR>
211                                                         <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
212                                                         <TD VALIGN="top">
213                                                                 man language reference
214                                                                 <SPAN STYLE="font-size: smaller;">
215                                                                         (<A HREF="man.7.txt">text</A> | 
216                                                                         <A HREF="man.7.xhtml">xhtml</A> |
217                                                                         <A HREF="man.7.pdf">pdf</A> |
218                                                                         <A HREF="man.7.ps">postscript</A>)
219                                                                 </SPAN>
220                                                         </TD>
221                                                 </TR>
222                                                 <TR>
223                                                         <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
224                                                         <TD VALIGN="top">
225                                                                 mandoc special characters
226                                                                 <SPAN STYLE="font-size: smaller;">
227                                                                         (<A HREF="mandoc_char.7.txt">text</A> | 
228                                                                         <A HREF="mandoc_char.7.xhtml">xhtml</A> |
229                                                                         <A HREF="mandoc_char.7.pdf">pdf</A> |
230                                                                         <A HREF="mandoc_char.7.ps">postscript</A>)
231                                                                 </SPAN>
232                                                         </TD>
233                                                 </TR>
234                                                 <TR>
235                                                         <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
236                                                         <TD VALIGN="top">
237                                                                 mdoc language reference
238                                                                 <SPAN STYLE="font-size: smaller;">
239                                                                         (<A HREF="mdoc.7.txt">text</A> | 
240                                                                         <A HREF="mdoc.7.xhtml">xhtml</A> |
241                                                                         <A HREF="mdoc.7.pdf">pdf</A> |
242                                                                         <A HREF="mdoc.7.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                                                 <TR>
259                                                         <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
260                                                         <TD VALIGN="top">
261                                                                 tbl-mandoc language reference
262                                                                 <SPAN STYLE="font-size: smaller;">
263                                                                         (<A HREF="tbl.7.txt">text</A> | 
264                                                                         <A HREF="tbl.7.xhtml">xhtml</A> |
265                                                                         <A HREF="tbl.7.pdf">pdf</A> |
266                                                                         <A HREF="tbl.7.ps">postscript</A>)
267                                                                 </SPAN>
268                                                         </TD>
269                                                 </TR>
270                                         </TBODY>
271                                         </TABLE>
272
273                                         <P>
274                                         See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
275                                         introduction to manpages and mdoc.
276                                         </P>
277                                 </TD>
278                         </TR>
279                         <TR>
280                                 <TD>
281                                         <H1>
282                                         <A NAME="contact">CONTACT</A>
283                                         </H1>
284
285                                         <P>
286                                                 Please use the mailing lists for bug-reports, patches, questions, etc. (these require
287                                                 subscription).  Beyond that, contact Kristaps at <A
288                                                 HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q=="
289                                                 TITLE="Reveal this e-mail address">kris...</A>@bsd.lv.
290                                         </P>
291
292                                         <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
293                                                 <COL WIDTH="175">
294                                                 <COL>
295                                                 <TBODY>
296                                                         <TR>
297                                                                 <TD>
298                                                                         disc<A CLASS="external" TITLE="Reveal this e-mail address"
299                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
300                                                                 </TD>
301                                                                 <TD>
302                                                                         bug-reports, general questions, and announcements 
303                                                                         <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/discuss/summary.html">archive</A>)</SPAN>
304                                                                 </TD>
305                                                         </TR>
306                                                         <TR>
307                                                                 <TD>
308                                                                         tec<A CLASS="external" TITLE="Reveal this e-mail address"
309                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&amp;c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
310                                                                 </TD>
311                                                                 <TD>
312                                                                         patches and system discussions 
313                                                                         <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/tech/summary.html">archive</A>)</SPAN>
314                                                                 </TD>
315                                                         </TR>
316                                                         <TR>
317                                                                 <TD>
318                                                                         sou<A CLASS="external" TITLE="Reveal this e-mail address"
319                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
320                                                                 </TD>
321                                                                 <TD>
322                                                                         source commit messages 
323                                                                         <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/source/summary.html">archive</A>)</SPAN>
324                                                                 </TD>
325                                                         </TR>
326                                                 </TBODY>
327                                         </TABLE>
328                                 </TD>
329                         </TR>
330                         <TR>
331                                 <TD>
332                                         <H1>
333                                         <A NAME="news">NEWS</A>
334                                         </H1>
335                                         <DIV CLASS="news">
336                                                 <P>
337                                                         <SPAN CLASS="date">07-01-2011</SPAN>:
338                                                         version 1.10.9
339                                                 </P>
340                                                 <P>
341                                                         Many back-end fixes have been implemented: argument handling (quoting), <A
342                                                         HREF="man.7.html">man</A> improvements, error/warning classes, and many more.
343                                                 </P>
344                                                 <P>
345                                                         Initial <A HREF="tbl.7.html">tbl</A> functionality (see the <Q>TS</Q>, <Q>TE</Q>, and
346                                                         <Q>T&amp;</Q> macros in the <A HREF="roff.7.html#x5c265453">roff</A> manual) has been
347                                                         merged from <A CLASS="external" HREF="http://tbl.bsd.lv">tbl.bsd.lv</A>.  Output is
348                                                         still minimal, especially for <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
349                                                         CLASS="flag">-Txhtml</SPAN>, but manages to at least display data.  This means that <A
350                                                         HREF="mandoc.1.html">mandoc</A> now has built-in support for two troff preprocessors via
351                                                         <A HREF="roff.3.html">libroff</A>: soelim and tbl.
352                                                 </P>
353                                         </DIV>
354                                         <DIV CLASS="news">
355                                                 <P>
356                                                         <SPAN CLASS="date">24-12-2010</SPAN>:
357                                                         version 1.10.8
358                                                 </P>
359                                                 <P>
360                                                         Significant improvements merged from <A CLASS="external"
361                                                         HREF="http://www.openbsd.org">OpenBSD</A> downstream, including
362                                                 </P>
363                                                 <UL>
364                                                         <LI>many new <A HREF="roff.7.html">roff</A> components,</LI>
365                                                         <LI>in-line implementation of troff's soelim,</LI>
366                                                         <LI>broken-block handling,</LI>
367                                                         <LI>overhauled error classifications, and</LI>
368                                                         <LI>cleaned up handling of error conditions.</LI>
369                                                 </UL>
370                                                 <P>
371                                                         Also overhauled the <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
372                                                         CLASS="flag">-Txhtml</SPAN> output modes.  They now display readable output in arbitrary
373                                                         browsers, including text-based ones like <A CLASS="external"
374                                                         HREF="http://lynx.isc.org">lynx</A>.  See HTML and XHTML manuals in the <A
375                                                         HREF="#documentation">DOCUMENTATION</A> section for examples.  <SPAN
376                                                         CLASS="attn">Attention: available style-sheet classes have been considerably
377                                                         changed!</SPAN> See the <SPAN CLASS="file">example.style.css</SPAN> file for details.
378                                                         Lastly, <A HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> have been
379                                                         cleaned up and reduced in size and complexity.
380                                                 </P>
381                                         </DIV>
382                                         <P>
383                                                 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
384                                                 historical notes.
385                                         </P>
386                                 </TD>
387                         </TR>
388                         <TR>
389                                 <TD>
390                                         <DIV CLASS="foot">
391                                                 Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2011/01/07 13:10:03 $
392                                         </DIV>
393                                 </TD>
394                         </TR>
395                 </TBODY>
396         </TABLE>
397         </BODY>
398 </HTML>