Import mdocml-1.11.3
[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">
80387638
SW
5 <LINK REL="stylesheet" HREF="index.css" TYPE="text/css" MEDIA="all">
6 <TITLE>mdocml | mdoc macro compiler</TITLE>
7 </HEAD>
8 <BODY>
a4c7eb57
SW
9 <P CLASS="head">
10 <B>mdocml</B> &#8211; mdoc macro compiler
11 </P>
12 <H1>
13 <A NAME="description">Description</A>
14 </H1>
15 <P>
16 <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <I><A HREF="mdoc.7.html">mdoc</A></I>, the roff macro
17 package of choice for BSD manual pages, and <I><A HREF="man.7.html">man</A></I>, the predominant historical package for
18 UNIX manuals. The mission of <SPAN CLASS="nm">mdocml</SPAN> is to deprecate <A
19 HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU troff implementation, for displaying <I>mdoc</I>
20 pages whilst providing token support for <I>man</I>.
21 </P>
22 <P>
23 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
24 uncertain output, and varies in operation from system to system. mdocml strives to fix this (respectively small, C, <A
25 CLASS="external" HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
26 </P>
27 <P>
28 <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating compiler and <A
29 HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format output for UNIX terminals (with
30 support for wide-character locales), XHTML, HTML, PostScript, and PDF.
31 It also includes <A HREF="preconv.1.html">preconv</A>, for recoding multibyte manuals; and <A
32 HREF="makewhatis.1.html">makewhatis</A>, for indexing manuals.
33 It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.
34 </P>
35 <P>
36 <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary, <Q>mandoc</Q>.
37 </P>
38 <H1>
39 <A NAME="sources">Sources</A>
40 </H1>
41 <P>
42 <SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any UNIX system, although <A
43 HREF="makewhatis.1.html">makewhatis</A> requires <A CLASS="external"
44 HREF="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">Berkeley Database</A> (this is
45 installed by default on all BSD operating systems).
46 To compile <SPAN CLASS="nm">mdocml</SPAN>, run <CODE>make</CODE>, then <CODE>make install</CODE> to install into
47 <I>/usr/local</I>.
48 Be aware: if you have an existing <A HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A> installation,
49 this may overwrite its <B>preconv</B> binary.
50 The <A HREF="makewhatis.1.html">makewhatis</A> utility is not yet linked to the build. You must run <CODE>make
51 makewhatis</CODE> to build it (it does not install).
52 </P>
53 <P>
54 The most current version of <SPAN CLASS="nm">mdocml</SPAN> is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN
55 class="attn">@VDATE@</SPAN>.
56 </P>
80387638 57
a4c7eb57
SW
58 <H2>
59 Current
60 </H2>
80387638 61
a4c7eb57
SW
62 <TABLE WIDTH="100%" SUMMARY="Current Sources">
63 <COL WIDTH="175">
64 <COL>
65 <TBODY>
66 <TR>
67 <TD>Source archive</TD>
68 <TD>
69 <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
70 <SMALL>(<A HREF="/snapshots/mdocml.md5">md5</A>)</SMALL>
71 </TD>
72 </TR>
73 <TR>
74 <TD>Online source</TD>
75 <TD>
76 <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
77 </TD>
78 </TR>
79 </TBODY>
80 </TABLE>
80387638 81
a4c7eb57
SW
82 <H2>
83 Downstream
84 </H2>
80387638 85
a4c7eb57
SW
86 <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
87 <COL WIDTH="175">
88 <COL>
89 <TBODY>
90 <TR>
91 <TD>DragonFly BSD</TD>
92 <TD>
93 <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
94 CLASS="external">usr.bin/mandoc</A>
95 </TD>
96 </TR>
97 <TR>
98 <TD>FreeBSD</TD>
99 <TD>
100 <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
101 CLASS="external">ports/textproc/mdocml</A>
102 </TD>
103 </TR>
104 <TR>
105 <TD>NetBSD</TD>
106 <TD>
107 <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
108 CLASS="external">src/external/bsd/mdocml</A>
109 </TD>
110 </TR>
111 <TR>
112 <TD>OpenBSD</TD>
113 <TD>
114 <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
115 CLASS="external">src/usr.bin/mandoc</A>
116 </TD>
117 </TR>
118 </TBODY>
119 </TABLE>
80387638 120
a4c7eb57
SW
121 <H2>
122 Historical
123 </H2>
80387638 124
a4c7eb57
SW
125 <TABLE WIDTH="100%" SUMMARY="Archived Sources">
126 <COL WIDTH="175">
127 <COL>
128 <TBODY>
129 <TR>
130 <TD>Source archive</TD>
131 <TD>
132 <A HREF="/snapshots/">/snapshots/</A>
133 </TD>
134 </TR>
135 </TBODY>
136 </TABLE>
80387638 137
a4c7eb57
SW
138 <H1>
139 <A NAME="documentation">Documentation</A>
140 </H1>
80387638 141
a4c7eb57
SW
142 <P>
143 These manuals are generated automatically and refer to the current snapshot.
144 </P>
80387638 145
a4c7eb57
SW
146 <TABLE WIDTH="100%" SUMMARY="Documentation">
147 <COL WIDTH="175">
148 <COL>
149 <TBODY>
150 <TR>
151 <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
152 <TD VALIGN="top">
153 format and display UNIX manuals
154 <SMALL>
155 (<A HREF="mandoc.1.txt">text</A> |
156 <A HREF="mandoc.1.xhtml">xhtml</A> |
157 <A HREF="mandoc.1.pdf">pdf</A> |
158 <A HREF="mandoc.1.ps">postscript</A>)
159 </SMALL>
160 </TD>
161 </TR>
162 <TR>
163 <TD VALIGN="top"><A HREF="makewhatis.1.html">makewhatis(1)</A></TD>
164 <TD VALIGN="top">
165 index UNIX manuals
166 <SMALL>
167 (<A HREF="makewhatis.1.txt">text</A> |
168 <A HREF="makewhatis.1.xhtml">xhtml</A> |
169 <A HREF="makewhatis.1.pdf">pdf</A> |
170 <A HREF="makewhatis.1.ps">postscript</A>)
171 </SMALL>
172 </TD>
173 </TR>
174 <TR>
175 <TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD>
176 <TD VALIGN="top">
177 recode multibyte UNIX manuals
178 <SMALL>
179 (<A HREF="preconv.1.txt">text</A> |
180 <A HREF="preconv.1.xhtml">xhtml</A> |
181 <A HREF="preconv.1.pdf">pdf</A> |
182 <A HREF="preconv.1.ps">postscript</A>)
183 </SMALL>
184 </TD>
185 </TR>
186 <TR>
187 <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
188 <TD VALIGN="top">
189 mandoc macro compiler library
190 <SMALL>
191 (<A HREF="mandoc.3.txt">text</A> |
192 <A HREF="mandoc.3.xhtml">xhtml</A> |
193 <A HREF="mandoc.3.pdf">pdf</A> |
194 <A HREF="mandoc.3.ps">postscript</A>)
195 </SMALL>
196 </TD>
197 </TR>
198 <TR>
199 <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
200 <TD VALIGN="top">
201 man language reference
202 <SMALL>
203 (<A HREF="man.7.txt">text</A> |
204 <A HREF="man.7.xhtml">xhtml</A> |
205 <A HREF="man.7.pdf">pdf</A> |
206 <A HREF="man.7.ps">postscript</A>)
207 </SMALL>
208 </TD>
209 </TR>
210 <TR>
211 <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
212 <TD VALIGN="top">
213 eqn-mandoc language reference
214 <SMALL>
215 (<A HREF="eqn.7.txt">text</A> |
216 <A HREF="eqn.7.xhtml">xhtml</A> |
217 <A HREF="eqn.7.pdf">pdf</A> |
218 <A HREF="eqn.7.ps">postscript</A>)
219 </SMALL>
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 <SMALL>
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 </SMALL>
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 <SMALL>
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 </SMALL>
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 <SMALL>
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 </SMALL>
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 <SMALL>
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 </SMALL>
268 </TD>
269 </TR>
270 </TBODY>
271 </TABLE>
80387638 272
a4c7eb57
SW
273 <H1>
274 <A NAME="contact">Contact</A>
275 </H1>
80387638 276
a4c7eb57
SW
277 <P>
278 Use the mailing lists for bug-reports, patches, questions, etc. (these require subscription). Please check the
279 <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
280 before posting. Beyond that, contact Kristaps at <A
281 HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
282 this e-mail address">kris...</A>@bsd.lv.
283 </P>
80387638 284
a4c7eb57
SW
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 <SMALL>(<A HREF="/archives/discuss/summary.html">archive</A>)</SMALL>
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 <SMALL>(<A HREF="/archives/tech/summary.html">archive</A>)</SMALL>
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 <SMALL>(<A HREF="/archives/source/summary.html">archive</A>)</SMALL>
317 </TD>
318 </TR>
319 </TBODY>
320 </TABLE>
80387638 321
a4c7eb57
SW
322 <H1>
323 <A NAME="news">News</A>
324 </H1>
80387638 325
a4c7eb57
SW
326 <P CLASS="news">
327 26-05-2011: version 1.11.3
328 </P>
329 <P>
330 Introduce locale-encoding of output with the <B>-Tlocale</B> output option and Unicode escaped-character input.
331 See <A HREF="mandoc.1.html">mandoc</A> and <A HREF="mandoc_char.7.html">mandoc_char</A>, respectively, for details.
332 This allows for non-ASCII characters (e.g., <I>\[u5000]</I>) to be rendered in the locale's encoding, if said
333 environment supports wide-character encoding (if it does not, <B>-Tascii</B> is used instead).
334 Locale support can be turned off at compile time by removing <I>-DUSE_WCHAR</I> in the <I>Makefile</I>, in which case
335 <B>-Tlocale</B> is always a synonym for <B>-Tascii</B>.
336 </P>
337 <P>
338 Furthermore, multibyte-encoded documents, such as those in UTF-8, may be on-the-fly recoded into <A
339 HREF="mandoc.1.html">mandoc</A> input by using the newly-added <A HREF="preconv.1.html">preconv</A> utility.
340 Note: in the future, this feature may be integrated into <A HREF="mandoc.1.html">mandoc</A>.
341 </P>
80387638 342
a4c7eb57
SW
343 <P CLASS="news">
344 12-05-2011: version 1.11.2
345 </P>
346 <P>
347 Corrected some installation issues in version 1.11.1.
348 Further migration to <A HREF="mandoc.3.html">libmandoc</A>.
349 Initial public release (this utility is very much under development) of <A HREF="makewhatis.1.html">makewhatis</A>,
350 initially named mandoc-db.
351 This utility produces keyword databases of manual content
352 <A HREF="http://mdocml.bsd.lv/mandoc-cgi/index.html">mandoc-cgi</A>, which features semantic querying of manual content.
353 </P>
80387638 354
a4c7eb57
SW
355 <P CLASS="news">
356 04-04-2011: version 1.11.1
357 </P>
358 <P>
359 The earlier <I>libroff</I>, <I>libmdoc</I>, and <I>libman</I> soup have been merged into
360 a single library, <A HREF="mandoc.3.html">libmandoc</A>, which manages all aspects of
361 parsing real manuals (from line-handling to <A HREF="tbl.7.html">tbl</A> parsing).
362 </P>
363 <P>
364 Beyond this structural change, initial <A HREF="eqn.7.html">eqn</A> functionality is in
365 place. For the time being, this is limited to the recognition of equation blocks;
366 future version of <SPAN CLASS="nm">mdocml</SPAN> will expand upon this framework.
367 </P>
368 <P>
369 As usual, many general fixes and improvements have also occurred. In particular, a great
370 deal of redundancy and superfluous code has been removed with the merging of the backend
371 libraries.
372 </P>
373
374 <P>
375 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
376 historical notes.
377 </P>
378
379 <P CLASS="foot">
380 <SMALL>
381 Copyright &#169; 2008&#8211;2011
382 <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
383 $Date: 2011/05/26 21:23:50 $
384 </SMALL>
385 </P>
80387638
SW
386 </BODY>
387</HTML>