Import mdocml-1.12.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">
80387638 5 <LINK REL="stylesheet" HREF="index.css" TYPE="text/css" MEDIA="all">
36342e81 6 <TITLE>mdocml | UNIX manpage compiler</TITLE>
80387638
SW
7 </HEAD>
8 <BODY>
a4c7eb57 9 <P CLASS="head">
36342e81
SW
10 <B>mdocml</B> &#8211; UNIX manpage compiler, current version @VERSION@ (@VDATE@)
11 </P>
12 <P CLASS="subhead">
13 Sources: <A HREF="/snapshots/mdocml.tar.gz">current</A>,
14 <A HREF="/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
15 (<A HREF="/snapshots/">archives</A>)
a4c7eb57
SW
16 </P>
17 <H1>
18 <A NAME="description">Description</A>
19 </H1>
20 <P>
21 <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <I><A HREF="mdoc.7.html">mdoc</A></I>, the roff macro
22 package of choice for BSD manual pages, and <I><A HREF="man.7.html">man</A></I>, the predominant historical package for
23 UNIX manuals. The mission of <SPAN CLASS="nm">mdocml</SPAN> is to deprecate <A
24 HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU troff implementation, for displaying <I>mdoc</I>
25 pages whilst providing token support for <I>man</I>.
26 </P>
27 <P>
28 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
29 uncertain output, and varies in operation from system to system. mdocml strives to fix this (respectively small, C, <A
30 CLASS="external" HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
31 </P>
32 <P>
33 <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating compiler and <A
34 HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format output for UNIX terminals (with
35 support for wide-character locales), XHTML, HTML, PostScript, and PDF.
36342e81
SW
36 It also includes <A HREF="preconv.1.html">preconv</A>, for recoding multibyte manuals;
37 <A HREF="demandoc.1.html">demandoc</A>, for emitting only text parts of manuals;
38 <A HREF="mandocdb.8.html">mandocdb</A>, for indexing manuals; and
39 <A HREF="apropos.1.html">apropos</A>, <A HREF="whatis.1.html">whatis</A>, and
40 <A HREF="man.cgi.7.html">man.cgi</A> (via <A HREF="catman.8.html">catman</A>) for semantic search of manual content.
a4c7eb57
SW
41 It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.
42 </P>
43 <P>
44 <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary, <Q>mandoc</Q>.
45 </P>
36342e81 46 <H2>
a4c7eb57 47 <A NAME="sources">Sources</A>
36342e81 48 </H2>
a4c7eb57 49 <P>
36342e81
SW
50 <SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any modern system; however, you'll
51 need <A HREF="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">libdb</A> to build <A
52 HREF="apropos.1.html">apropos</A>, <A HREF="whatis.1.html">whatis</A>, <A HREF="man.cgi.7.html">man.cgi</A>, <A
53 HREF="catman.8.html">catman</A>, and <A HREF="mandocdb.8.html">mandocdb</A> (this is installed by default on BSD UNIX
54 systems &mdash; see the <I>Makefile</I> if you're running Linux). To build and install into <I>/usr/local/</I>, just
55 run <CODE>make install</CODE>. Be careful: the <B>preconv</B>, <B>apropos</B>, and <B>whatis</B> binary names are
56 usually taken by existing utilities.
a4c7eb57 57 </P>
a4c7eb57 58 <H2>
36342e81 59 <A NAME="binaries">Binaries</A>
a4c7eb57 60 </H2>
36342e81
SW
61 <P>
62 Binary archives consist of pre-compiled binaries, manuals, and other necessary files.
63 Universal (Mac OS X) binaries are compiled for the PCC, i386, and x86_64 architectures.
64 Windows binaries are compiled with <A CLASS="external" HREF="http://www.mingw.org">MingW</A> for the 32-bit (i686) and
65 64-bit (x86_64) architectures.
66 </P>
a4c7eb57
SW
67 <H2>
68 Downstream
69 </H2>
36342e81
SW
70 <P>
71 Several systems come bundled with <SPAN CLASS="nm">mdocml</SPAN> utilities.
72 If your system does not appear below, the maintainers have not contacted me and it should not be considered
73 <Q>official</Q>.
74 Please <A HREF="#contact">contact us</A> if you plan on maintaining a downstream version!
75 </P>
a4c7eb57
SW
76 <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
77 <COL WIDTH="175">
78 <COL>
79 <TBODY>
80 <TR>
81 <TD>DragonFly BSD</TD>
82 <TD>
36342e81 83 <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc" CLASS="external">usr.bin/mandoc</A>
a4c7eb57
SW
84 </TD>
85 </TR>
86 <TR>
87 <TD>FreeBSD</TD>
88 <TD>
36342e81 89 <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/" CLASS="external">ports/textproc/mdocml</A>
a4c7eb57
SW
90 </TD>
91 </TR>
92 <TR>
93 <TD>NetBSD</TD>
94 <TD>
36342e81 95 <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/" CLASS="external">src/external/bsd/mdocml</A>
a4c7eb57
SW
96 </TD>
97 </TR>
98 <TR>
99 <TD>OpenBSD</TD>
100 <TD>
36342e81 101 <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/" CLASS="external">src/usr.bin/mandoc</A>
a4c7eb57
SW
102 </TD>
103 </TR>
a4c7eb57 104 <TR>
36342e81 105 <TD>pkgsrc</TD>
a4c7eb57 106 <TD>
36342e81
SW
107 <A HREF="http://pkgsrc.se/textproc/mdocml" CLASS="external">textproc/mdocml</A>
108 </TD>
109 </TR>
110 <TR>
111 <TD>Minix3</TD>
112 <TD>
113 <A HREF="http://git.minix3.org/?p=minix.git;a=tree;f=external/bsd/mdocml" CLASS="external">external/bsd/mdocml</A>
a4c7eb57
SW
114 </TD>
115 </TR>
116 </TBODY>
117 </TABLE>
a4c7eb57
SW
118 <H1>
119 <A NAME="documentation">Documentation</A>
120 </H1>
a4c7eb57 121 <P>
36342e81
SW
122 These manuals are generated automatically and refer to the current release.
123 They are the authoritative documentation for the <SPAN CLASS="nm">mdocml</SPAN> system.
a4c7eb57 124 </P>
80387638 125
a4c7eb57
SW
126 <TABLE WIDTH="100%" SUMMARY="Documentation">
127 <COL WIDTH="175">
128 <COL>
129 <TBODY>
36342e81
SW
130 <TR>
131 <TD VALIGN="top"><A HREF="apropos.1.html">apropos(1)</A></TD>
132 <TD VALIGN="top">
133 search the manual page database
134 (<A HREF="apropos.1.txt">text</A> |
135 <A HREF="apropos.1.xhtml">xhtml</A> |
136 <A HREF="apropos.1.pdf">pdf</A> |
137 <A HREF="apropos.1.ps">ps</A>)
138 </TD>
139 </TR>
140 <TR>
141 <TD VALIGN="top"><A HREF="demandoc.1.html">demandoc(1)</A></TD>
142 <TD VALIGN="top">
143 emit only text of UNIX manuals
144 (<A HREF="demandoc.1.txt">text</A> |
145 <A HREF="demandoc.1.xhtml">xhtml</A> |
146 <A HREF="demandoc.1.pdf">pdf</A> |
147 <A HREF="demandoc.1.ps">ps</A>)
148 </TD>
149 </TR>
a4c7eb57
SW
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
a4c7eb57
SW
154 (<A HREF="mandoc.1.txt">text</A> |
155 <A HREF="mandoc.1.xhtml">xhtml</A> |
156 <A HREF="mandoc.1.pdf">pdf</A> |
36342e81 157 <A HREF="mandoc.1.ps">ps</A>)
a4c7eb57
SW
158 </TD>
159 </TR>
160 <TR>
161 <TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD>
162 <TD VALIGN="top">
163 recode multibyte UNIX manuals
a4c7eb57
SW
164 (<A HREF="preconv.1.txt">text</A> |
165 <A HREF="preconv.1.xhtml">xhtml</A> |
166 <A HREF="preconv.1.pdf">pdf</A> |
36342e81
SW
167 <A HREF="preconv.1.ps">ps</A>)
168 </TD>
169 </TR>
170 <TR>
171 <TD VALIGN="top"><A HREF="whatis.1.html">whatis(1)</A></TD>
172 <TD VALIGN="top">
173 search the manual page database
174 (<A HREF="whatis.1.txt">text</A> |
175 <A HREF="whatis.1.xhtml">xhtml</A> |
176 <A HREF="whatis.1.pdf">pdf</A> |
177 <A HREF="whatis.1.ps">ps</A>)
a4c7eb57
SW
178 </TD>
179 </TR>
180 <TR>
181 <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
182 <TD VALIGN="top">
183 mandoc macro compiler library
a4c7eb57
SW
184 (<A HREF="mandoc.3.txt">text</A> |
185 <A HREF="mandoc.3.xhtml">xhtml</A> |
186 <A HREF="mandoc.3.pdf">pdf</A> |
36342e81 187 <A HREF="mandoc.3.ps">ps</A>)
a4c7eb57
SW
188 </TD>
189 </TR>
190 <TR>
191 <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
192 <TD VALIGN="top">
193 man language reference
a4c7eb57
SW
194 (<A HREF="man.7.txt">text</A> |
195 <A HREF="man.7.xhtml">xhtml</A> |
196 <A HREF="man.7.pdf">pdf</A> |
36342e81
SW
197 <A HREF="man.7.ps">ps</A>)
198 </TD>
199 </TR>
200 <TR>
201 <TD VALIGN="top"><A HREF="man.cgi.7.html">man.cgi(7)</A></TD>
202 <TD VALIGN="top">
203 cgi for manpage query and display
204 (<A HREF="man.cgi.7.txt">text</A> |
205 <A HREF="man.cgi.7.xhtml">xhtml</A> |
206 <A HREF="man.cgi.7.pdf">pdf</A> |
207 <A HREF="man.cgi.7.ps">ps</A>)
a4c7eb57
SW
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
a4c7eb57
SW
214 (<A HREF="eqn.7.txt">text</A> |
215 <A HREF="eqn.7.xhtml">xhtml</A> |
216 <A HREF="eqn.7.pdf">pdf</A> |
36342e81 217 <A HREF="eqn.7.ps">ps</A>)
a4c7eb57
SW
218 </TD>
219 </TR>
220 <TR>
221 <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
222 <TD VALIGN="top">
223 mandoc special characters
a4c7eb57
SW
224 (<A HREF="mandoc_char.7.txt">text</A> |
225 <A HREF="mandoc_char.7.xhtml">xhtml</A> |
226 <A HREF="mandoc_char.7.pdf">pdf</A> |
36342e81 227 <A HREF="mandoc_char.7.ps">ps</A>)
a4c7eb57
SW
228 </TD>
229 </TR>
230 <TR>
231 <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
232 <TD VALIGN="top">
233 mdoc language reference
a4c7eb57
SW
234 (<A HREF="mdoc.7.txt">text</A> |
235 <A HREF="mdoc.7.xhtml">xhtml</A> |
236 <A HREF="mdoc.7.pdf">pdf</A> |
36342e81 237 <A HREF="mdoc.7.ps">ps</A>)
a4c7eb57
SW
238 </TD>
239 </TR>
240 <TR>
241 <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
242 <TD VALIGN="top">
243 roff-mandoc language reference
a4c7eb57
SW
244 (<A HREF="roff.7.txt">text</A> |
245 <A HREF="roff.7.xhtml">xhtml</A> |
246 <A HREF="roff.7.pdf">pdf</A> |
36342e81 247 <A HREF="roff.7.ps">ps</A>)
a4c7eb57
SW
248 </TD>
249 </TR>
250 <TR>
251 <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
252 <TD VALIGN="top">
253 tbl-mandoc language reference
a4c7eb57
SW
254 (<A HREF="tbl.7.txt">text</A> |
255 <A HREF="tbl.7.xhtml">xhtml</A> |
256 <A HREF="tbl.7.pdf">pdf</A> |
36342e81
SW
257 <A HREF="tbl.7.ps">ps</A>)
258 </TD>
259 </TR>
260 <TR>
261 <TD VALIGN="top"><A HREF="catman.8.html">catman(8)</A></TD>
262 <TD VALIGN="top">
263 update a man.cgi manpage cache
264 (<A HREF="catman.8.txt">text</A> |
265 <A HREF="catman.8.xhtml">xhtml</A> |
266 <A HREF="catman.8.pdf">pdf</A> |
267 <A HREF="catman.8.ps">ps</A>)
268 </TD>
269 </TR>
270 <TR>
271 <TD VALIGN="top"><A HREF="mandocdb.8.html">mandocdb(8)</A></TD>
272 <TD VALIGN="top">
273 index UNIX manuals
274 (<A HREF="mandocdb.8.txt">text</A> |
275 <A HREF="mandocdb.8.xhtml">xhtml</A> |
276 <A HREF="mandocdb.8.pdf">pdf</A> |
277 <A HREF="mandocdb.8.ps">ps</A>)
a4c7eb57
SW
278 </TD>
279 </TR>
280 </TBODY>
281 </TABLE>
a4c7eb57
SW
282 <H1>
283 <A NAME="contact">Contact</A>
284 </H1>
a4c7eb57 285 <P>
36342e81 286 Use the mailing lists for bug-reports, patches, questions, etc. Please check the
a4c7eb57 287 <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
36342e81
SW
288 before posting. All lists are subscription-only: send a blank e-mail to the listed address to subscribe. Beyond that,
289 contact Kristaps at <A HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
290 this e-mail address">kris...</A>@bsd.lv. Archives are available at <A HREF="http://gmane.org/" CLASS="external">Gmane</A>.
a4c7eb57 291 </P>
a4c7eb57
SW
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
a4c7eb57
SW
303 </TD>
304 </TR>
305 <TR>
306 <TD>
307 tec<A CLASS="external" TITLE="Reveal this e-mail address"
308 HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&amp;c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
309 </TD>
310 <TD>
311 patches and system discussions
a4c7eb57
SW
312 </TD>
313 </TR>
314 <TR>
315 <TD>
316 sou<A CLASS="external" TITLE="Reveal this e-mail address"
317 HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
318 </TD>
319 <TD>
320 source commit messages
a4c7eb57
SW
321 </TD>
322 </TR>
323 </TBODY>
324 </TABLE>
a4c7eb57
SW
325 <H1>
326 <A NAME="news">News</A>
327 </H1>
a4c7eb57 328 <P CLASS="news">
36342e81 329 23-03-2011: version 1.12.1
a4c7eb57
SW
330 </P>
331 <P>
36342e81
SW
332 Significant work on <A HREF="apropos.1.html">apropos</A> and <A HREF="mandocdb.8.html">mandocdb</A>. These tools are
333 now much more robust.
334 A <A HREF="whatis.1.html">whatis</A> implementation is now handled as an <A HREF="apropos.1.html">apropos</A> mode.
335 These tools are also able to minimally handle pre-formatted pages, that is, those already formatted by another utility
336 such as GNU troff.
a4c7eb57
SW
337 </P>
338 <P>
36342e81
SW
339 The <A HREF="man.cgi.7.html">man.cgi</A> script is also now available for wider testing. It interfaces with <A
340 HREF="mandocdb.8.html">mandocdb</A> manuals cached by <A HREF="catman.8.html">catman</A>. HTML output is generated
341 on-the-fly by <A HREF="mandoc.3.html">libmandoc</A> or internal methods to convert pre-formatted pages.
a4c7eb57
SW
342 </P>
343 <P>
36342e81
SW
344 The mailing list archive for the discuss and tech lists are being hosted by <A CLASS="external"
345 HREF="http://www.gmane.org">Gmane</A> at <A HREF="http://dir.gmane.org/gmane.comp.tools.mdocml.user"
346 CLASS="external">gmane.comp.tools.mdocml.user</A> and <A HREF="http://dir.gmane.org/gmane.comp.tools.mdocml.devel"
347 CLASS="external">gmane.comp.tools.mdocml.devel</A>, respectively.
a4c7eb57
SW
348 </P>
349 <P>
36342e81 350 Lastly, I'm no longer providing binaries, as nobody has asked for them.
a4c7eb57 351 </P>
a4c7eb57
SW
352 <P>
353 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
354 historical notes.
355 </P>
a4c7eb57
SW
356 <P CLASS="foot">
357 <SMALL>
358 Copyright &#169; 2008&#8211;2011
359 <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
36342e81 360 $Date: 2012/03/24 02:07:32 $
a4c7eb57
SW
361 </SMALL>
362 </P>
80387638
SW
363 </BODY>
364</HTML>