Annotation of mandoc/index.sgml, Revision 1.154.2.14
1.1 kristaps 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
1.40 kristaps 2: <HTML>
3: <HEAD>
4: <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
5: <LINK REL="stylesheet" HREF="index.css" TYPE="text/css" MEDIA="all">
1.149 kristaps 6: <TITLE>mdocml | UNIX manpage compiler</TITLE>
1.40 kristaps 7: </HEAD>
8: <BODY>
1.112 kristaps 9: <P CLASS="head">
1.154.2.12 schwarze 10: <A HREF="http://www.openbsd.org/"><IMG SRC="puffy.gif" ALT="Puffy" WIDTH="100" HEIGHT="91" STYLE="float: right"></A>
1.149 kristaps 11: <B>mdocml</B> – UNIX manpage compiler, current version @VERSION@ (@VDATE@)
1.136 kristaps 12: </P>
13: <P CLASS="subhead">
14: Sources: <A HREF="/snapshots/mdocml.tar.gz">current</A>,
15: <A HREF="/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
16: (<A HREF="/snapshots/">archives</A>)
1.112 kristaps 17: </P>
18: <H1>
1.118 kristaps 19: <A NAME="description">Description</A>
1.112 kristaps 20: </H1>
21: <P>
22: <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <I><A HREF="mdoc.7.html">mdoc</A></I>, the roff macro
23: package of choice for BSD manual pages, and <I><A HREF="man.7.html">man</A></I>, the predominant historical package for
1.154.2.12 schwarze 24: UNIX manuals.
25: It is small, ISO C, <A CLASS="external" HREF="http://www.isc.org/software/license">ISC</A>-licensed, and quite fast.
1.112 kristaps 26: </P>
27: <P>
1.154.2.13 schwarze 28: The tool set features <A HREF="mandoc.1.html">mandoc</A>,
29: based on the <A HREF="mandoc.3.html">libmandoc</A> validating compiler,
30: to format output for UNIX terminals (with
1.121 kristaps 31: support for wide-character locales), XHTML, HTML, PostScript, and PDF.
1.138 kristaps 32: It also includes <A HREF="preconv.1.html">preconv</A>, for recoding multibyte manuals;
33: <A HREF="demandoc.1.html">demandoc</A>, for emitting only text parts of manuals;
1.144 kristaps 34: <A HREF="mandocdb.8.html">mandocdb</A>, for indexing manuals; and
1.150 kristaps 35: <A HREF="apropos.1.html">apropos</A>, <A HREF="whatis.1.html">whatis</A>, and
36: <A HREF="man.cgi.7.html">man.cgi</A> (via <A HREF="catman.8.html">catman</A>) for semantic search of manual content.
1.154.2.12 schwarze 37: </P>
38: <P>
39: <SPAN CLASS="nm">mdocml</SPAN> has predominantly been developed on OpenBSD
40: and is both an <A CLASS="external" HREF="http://www.openbsd.org/">OpenBSD</A>
41: and a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.
42: We strive to support all interested free operating systems, in particular
43: <A CLASS="external" HREF="http://www.dragonflybsd.org/">DragonFly</A>,
1.154.2.14! schwarze 44: <A CLASS="external" HREF="http://www.netbsd.org/">NetBSD</A>,
1.154.2.12 schwarze 45: <A CLASS="external" HREF="http://www.freebsd.org/">FreeBSD</A>,
46: <A CLASS="external" HREF="http://www.minix3.org/">Minix 3</A>,
47: and <A CLASS="external" HREF="http://www.gnu.org/">GNU</A>/Linux,
48: as well as all systems running the <A CLASS="external" HREF="http://www.pkgsrc.org/">pkgsrc</A> portable package build system.
49: All of these projects have helped to make <SPAN CLASS="nm">mdocml</SPAN> better, by providing feedback and advice,
50: bug reports, and patches.
1.112 kristaps 51: </P>
52: <P>
53: <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary, <Q>mandoc</Q>.
54: </P>
1.137 kristaps 55: <H2>
1.118 kristaps 56: <A NAME="sources">Sources</A>
1.137 kristaps 57: </H2>
1.112 kristaps 58: <P>
1.154.2.13 schwarze 59: <SPAN CLASS="nm">mdocml</SPAN> should build and run on any modern system with
60: <A HREF="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">libdb</A>
61: (this is installed by default on BSD UNIX systems — see the <I>Makefile</I> if you're running Linux).
62: To build and install into <I>/usr/local/</I>, just run <CODE>make install</CODE>.
63: Be careful: the <B>preconv</B>, <B>apropos</B>, and <B>whatis</B> installed binary names
64: may be taken by existing utilities.
1.132 kristaps 65: </P>
1.137 kristaps 66: <H2>
1.112 kristaps 67: Downstream
1.137 kristaps 68: </H2>
1.135 kristaps 69: <P>
70: Several systems come bundled with <SPAN CLASS="nm">mdocml</SPAN> utilities.
71: If your system does not appear below, the maintainers have not contacted me and it should not be considered
1.154.2.13 schwarze 72: <Q>official</Q>, so please <A HREF="#contact">contact us</A> if you plan on maintaining a downstream version!
1.135 kristaps 73: </P>
1.112 kristaps 74: <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
1.136 kristaps 75: <COL WIDTH="175">
1.112 kristaps 76: <COL>
77: <TBODY>
78: <TR>
79: <TD>DragonFly BSD</TD>
80: <TD>
1.154.2.14! schwarze 81: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/contrib/mdocml" CLASS="external">contrib/mdocml</A> (post-1.12.2 sources)
1.154.2.4 schwarze 82: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/lib/libmandoc" CLASS="external">lib/libmandoc</A>
83: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc" CLASS="external">usr.bin/mandoc</A> (build system)
1.112 kristaps 84: </TD>
85: </TR>
86: <TR>
1.154.2.5 schwarze 87: <TD>FreeBSD 10.0, -CURRENT</TD>
1.112 kristaps 88: <TD>
1.154.2.5 schwarze 89: <A HREF="http://svnweb.freebsd.org/base/head/contrib/mdocml/" CLASS="external">contrib/mdocml</A> (1.12.1 sources)
90: <A HREF="http://svnweb.freebsd.org/base/head/usr.bin/mandoc/" CLASS="external">usr.bin/mandoc</A> (build system)
91: </TD>
92: </TR>
93: <TR>
94: <TD>FreeBSD 9.x, 8.x</TD>
95: <TD>
1.154.2.14! schwarze 96: <A HREF="http://svnweb.freebsd.org/ports/head/textproc/mdocml/" CLASS="external">ports/textproc/mdocml</A> (1.12.2 port)
1.112 kristaps 97: </TD>
98: </TR>
99: <TR>
100: <TD>NetBSD</TD>
101: <TD>
1.154.2.4 schwarze 102: <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/" CLASS="external">src/external/bsd/mdocml</A> (1.12.1 sources plus patches and build system)
1.112 kristaps 103: </TD>
104: </TR>
105: <TR>
106: <TD>OpenBSD</TD>
107: <TD>
1.154.2.14! schwarze 108: <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/" CLASS="external">src/usr.bin/mandoc</A> (post-1.12.2 sources under active development and build system)
1.112 kristaps 109: </TD>
110: </TR>
1.148 kristaps 111: <TR>
112: <TD>pkgsrc</TD>
113: <TD>
1.154.2.8 schwarze 114: <A HREF="http://pkgsrc.se/textproc/mdocml" CLASS="external">textproc/mdocml</A> (1.12.2 port)
1.148 kristaps 115: </TD>
116: </TR>
1.153 kristaps 117: <TR>
118: <TD>Minix3</TD>
119: <TD>
1.154.2.4 schwarze 120: <A HREF="http://git.minix3.org/?p=minix.git;a=tree;f=external/bsd/mdocml" CLASS="external">external/bsd/mdocml</A> (1.10.9 sources and build system)
1.153 kristaps 121: </TD>
122: </TR>
1.154.2.6 schwarze 123: <TR>
124: <TD>Alpine Linux</TD>
125: <TD>
1.154.2.10 schwarze 126: <A HREF="http://git.alpinelinux.org/cgit/aports/tree/main/mdocml" CLASS="external">aports/main/mdocml</A> (1.12.2 port)
1.154.2.6 schwarze 127: </TD>
128: </TR>
1.112 kristaps 129: </TBODY>
130: </TABLE>
131: <H1>
1.118 kristaps 132: <A NAME="documentation">Documentation</A>
1.112 kristaps 133: </H1>
134: <P>
1.135 kristaps 135: These manuals are generated automatically and refer to the current release.
136: They are the authoritative documentation for the <SPAN CLASS="nm">mdocml</SPAN> system.
1.112 kristaps 137: </P>
138:
139: <TABLE WIDTH="100%" SUMMARY="Documentation">
1.136 kristaps 140: <COL WIDTH="175">
1.112 kristaps 141: <COL>
142: <TBODY>
143: <TR>
1.144 kristaps 144: <TD VALIGN="top"><A HREF="apropos.1.html">apropos(1)</A></TD>
1.112 kristaps 145: <TD VALIGN="top">
1.144 kristaps 146: search the manual page database
1.112 kristaps 147: </TD>
148: </TR>
149: <TR>
1.138 kristaps 150: <TD VALIGN="top"><A HREF="demandoc.1.html">demandoc(1)</A></TD>
1.114 kristaps 151: <TD VALIGN="top">
1.138 kristaps 152: emit only text of UNIX manuals
1.114 kristaps 153: </TD>
154: </TR>
155: <TR>
1.144 kristaps 156: <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
157: <TD VALIGN="top">
158: format and display UNIX manuals
159: </TD>
160: </TR>
161: <TR>
1.120 kristaps 162: <TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD>
163: <TD VALIGN="top">
164: recode multibyte UNIX manuals
165: </TD>
166: </TR>
167: <TR>
1.149 kristaps 168: <TD VALIGN="top"><A HREF="whatis.1.html">whatis(1)</A></TD>
169: <TD VALIGN="top">
170: search the manual page database
171: </TD>
172: </TR>
173: <TR>
1.112 kristaps 174: <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
175: <TD VALIGN="top">
176: mandoc macro compiler library
177: </TD>
178: </TR>
179: <TR>
1.154.2.2 schwarze 180: <TD VALIGN="top"><A HREF="tbl.3.html">tbl(3)</A></TD>
181: <TD VALIGN="top">
182: roff table parser library for mandoc
183: </TD>
184: </TR>
185: <TR>
1.154.2.4 schwarze 186: <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
1.112 kristaps 187: <TD VALIGN="top">
1.154.2.4 schwarze 188: eqn-mandoc language reference
1.112 kristaps 189: </TD>
190: </TR>
191: <TR>
1.154.2.4 schwarze 192: <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
1.150 kristaps 193: <TD VALIGN="top">
1.154.2.4 schwarze 194: man language reference
1.150 kristaps 195: </TD>
196: </TR>
197: <TR>
1.154.2.4 schwarze 198: <TD VALIGN="top"><A HREF="man.cgi.7.html">man.cgi(7)</A></TD>
1.112 kristaps 199: <TD VALIGN="top">
1.154.2.4 schwarze 200: cgi for manpage query and display
1.112 kristaps 201: </TD>
202: </TR>
203: <TR>
204: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
205: <TD VALIGN="top">
206: mandoc special characters
207: </TD>
208: </TR>
209: <TR>
210: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
211: <TD VALIGN="top">
212: mdoc language reference
213: </TD>
214: </TR>
215: <TR>
216: <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
217: <TD VALIGN="top">
218: roff-mandoc language reference
219: </TD>
220: </TR>
221: <TR>
222: <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
223: <TD VALIGN="top">
224: tbl-mandoc language reference
225: </TD>
226: </TR>
1.138 kristaps 227: <TR>
1.150 kristaps 228: <TD VALIGN="top"><A HREF="catman.8.html">catman(8)</A></TD>
229: <TD VALIGN="top">
230: update a man.cgi manpage cache
231: </TD>
232: </TR>
233: <TR>
1.138 kristaps 234: <TD VALIGN="top"><A HREF="mandocdb.8.html">mandocdb(8)</A></TD>
235: <TD VALIGN="top">
236: index UNIX manuals
237: </TD>
238: </TR>
1.112 kristaps 239: </TBODY>
240: </TABLE>
1.154.2.10 schwarze 241: <H2>
242: <A NAME="links">Supplementary Information</A>
243: </H2>
244: <UL>
245: <LI>
246: <A HREF="http://manpages.bsd.lv/">Practical UNIX Manuals</A>: mdoc tutorial by Kristaps Dzonsons
247: </LI>
248: <LI>
249: <A HREF="http://www.openbsd.org/faq/ports/specialtopics.html#Mandoc" CLASS="external">OpenBSD porting guide</A>
250: chapter regarding manual pages
251: </LI>
252: <LI>
253: <A HREF="press.html">Publications and media coverage</A>
254: concerning mdocml and mandoc
255: </LI>
256: <LI>
257: <A HREF="http://manpages.bsd.lv/history.html">History of UNIX Manpages</A>: a comprehensive overview by Kristaps Dzonsons
258: </LI>
259: </UL>
1.112 kristaps 260: <H1>
1.118 kristaps 261: <A NAME="contact">Contact</A>
1.112 kristaps 262: </H1>
263: <P>
1.139 kristaps 264: Use the mailing lists for bug-reports, patches, questions, etc. Please check the
1.112 kristaps 265: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
1.139 kristaps 266: before posting. All lists are subscription-only: send a blank e-mail to the listed address to subscribe. Beyond that,
267: contact Kristaps at <A HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
1.149 kristaps 268: this e-mail address">kris...</A>@bsd.lv. Archives are available at <A HREF="http://gmane.org/" CLASS="external">Gmane</A>.
1.112 kristaps 269: </P>
270: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
1.136 kristaps 271: <COL WIDTH="175">
1.112 kristaps 272: <COL>
273: <TBODY>
274: <TR>
275: <TD>
276: disc<A CLASS="external" TITLE="Reveal this e-mail address"
277: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
278: </TD>
279: <TD>
280: bug-reports, general questions, and announcements
281: </TD>
282: </TR>
283: <TR>
284: <TD>
285: tec<A CLASS="external" TITLE="Reveal this e-mail address"
286: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
287: </TD>
288: <TD>
289: patches and system discussions
290: </TD>
291: </TR>
292: <TR>
293: <TD>
294: sou<A CLASS="external" TITLE="Reveal this e-mail address"
295: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
296: </TD>
297: <TD>
298: source commit messages
299: </TD>
300: </TR>
301: </TBODY>
302: </TABLE>
303: <H1>
1.118 kristaps 304: <A NAME="news">News</A>
1.112 kristaps 305: </H1>
1.124 kristaps 306: <P CLASS="news">
1.154.2.9 schwarze 307: 05-10-2013: version 1.12.2
1.154.2.3 schwarze 308: </P>
309: <P>
1.154.2.4 schwarze 310: The <A HREF="mdoc.7.html">mdoc(7)</A> to <A HREF="man.7.html">man(7)</A> converter,
311: to be called as <CODE>mandoc -Tman</CODE>, is now fully functional.
1.154.2.3 schwarze 312: </P>
313: <P>
314: The <A HREF="mandoc.1.html">mandoc(1)</A> utility now supports the <CODE>-Ios</CODE> (default operating system)
315: input option, and the <CODE>-Tutf8</CODE> output mode now actually works.
316: </P>
317: <P>
1.154.2.4 schwarze 318: The <A HREF="mandocdb.8.html">mandocdb(8)</A> utility no longer truncates existing databases when starting to build new ones,
319: but only replaces them when the build actually succeeds.
1.154.2.3 schwarze 320: </P>
321: <P>
322: The <A HREF="man.7.html">man(7)</A> parser now supports the <EM>PD</EM> macro (paragraph distance),
323: and (for GNU man-ext compatibility only) <EM>EX</EM> (example block) and <EM>EE</EM> (example end).
324: Plus several bugfixes regarding indentation, line breaks, and vertical spacing,
325: and regarding <EM>RS</EM> following <EM>TP</EM>.
326: </P>
327: <P>
328: The <A HREF="roff.7.html">roff(7)</A> parser now supports the <EM>\f(BI</EM> (bold+italic) font escape,
329: the <EM>\z</EM> (zero cursor advance) escape and the <EM>cc</EM> (change control character)
330: and <EM>it</EM> (input line trap) requests.
1.154.2.4 schwarze 331: Plus bugfixes regarding the <EM>\t</EM> (tab) escape, nested escape sequences, and conditional requests.
1.154.2.3 schwarze 332: </P>
333: <P>
1.154.2.4 schwarze 334: In <A HREF="mdoc.7.html">mdoc(7)</A>, several bugs were fixed related to UTF-8 output of quoting enclosures,
1.154.2.3 schwarze 335: delimiter handling, list indentation and horizontal and vertical spacing,
1.154.2.4 schwarze 336: formatting of the <EM>Lk</EM>, <EM>%U</EM>, and <EM>%C</EM> macros,
1.154.2.3 schwarze 337: plus some bugfixes related to the handling of syntax errors like badly nested font blocks,
338: stray <EM>Ta</EM> macros outside column lists, unterminated <EM>It Xo</EM> blocks,
339: and non-text children of <EM>Nm</EM> blocks.
340: </P>
341: <P>
1.154.2.4 schwarze 342: In <A HREF="tbl.7.html">tbl(7)</A>, the width of horizontal spans and the vertical spacing around tables was corrected,
343: and in <A HREF="man.7.html">man(7)</A> files, a crash was fixed that was triggered by some particular unclosed <EM>T{</EM> macros.
1.154.2.3 schwarze 344: </P>
345: <P>
346: For mandoc developers, we now provide a <A HREF="tbl.3.html">tbl(3)</A> library manual and <CODE>gmdiff</CODE>,
1.154.2.4 schwarze 347: a very small, very simplistic groff-versus-mandoc output comparison tool.
1.154.2.3 schwarze 348: </P>
349: <P CLASS="news">
1.154.2.8 schwarze 350: 23-03-2012: version 1.12.1
1.149 kristaps 351: </P>
352: <P>
353: Significant work on <A HREF="apropos.1.html">apropos</A> and <A HREF="mandocdb.8.html">mandocdb</A>. These tools are
1.152 kristaps 354: now much more robust.
355: A <A HREF="whatis.1.html">whatis</A> implementation is now handled as an <A HREF="apropos.1.html">apropos</A> mode.
356: These tools are also able to minimally handle pre-formatted pages, that is, those already formatted by another utility
357: such as GNU troff.
1.150 kristaps 358: </P>
359: <P>
360: The <A HREF="man.cgi.7.html">man.cgi</A> script is also now available for wider testing. It interfaces with <A
361: HREF="mandocdb.8.html">mandocdb</A> manuals cached by <A HREF="catman.8.html">catman</A>. HTML output is generated
362: on-the-fly by <A HREF="mandoc.3.html">libmandoc</A> or internal methods to convert pre-formatted pages.
1.149 kristaps 363: </P>
1.151 kristaps 364: <P>
1.152 kristaps 365: The mailing list archive for the discuss and tech lists are being hosted by <A CLASS="external"
1.151 kristaps 366: HREF="http://www.gmane.org">Gmane</A> at <A HREF="http://dir.gmane.org/gmane.comp.tools.mdocml.user"
367: CLASS="external">gmane.comp.tools.mdocml.user</A> and <A HREF="http://dir.gmane.org/gmane.comp.tools.mdocml.devel"
368: CLASS="external">gmane.comp.tools.mdocml.devel</A>, respectively.
369: </P>
1.142 kristaps 370: <P>
1.152 kristaps 371: Lastly, I'm no longer providing binaries, as nobody has asked for them.
1.112 kristaps 372: </P>
1.154.2.11 schwarze 373: <H2>
374: <A>History</A>
375: </H2>
376: <UL>
377: <LI>
378: <A HREF="NEWS">Release notes</A> going back to release 1.9.15, February 18, 2010.
379: Briefly explaining the most important changes in each release in relatively easy terms.
380: Very many changes are not mentioned here.
381: </LI>
382: <LI>
383: <A HREF="history.html">Development history</A> going back to the beginning of the project, November 22, 2008.
384: One-line entries for important commits, releases, merges, hackathons and talks.
385: Makes it easy to find out who did what, and when, and when it became available where.
386: However, this is still incomplete, mentioning only a small fraction of all commits,
387: and to keep the size down, the individual entries are extremely terse and technical.
388: Feel free to look up more details and longer explanations about individual entries
389: in the ChangeLog or in CVS.
390: </LI>
391: <LI>
392: <A HREF="ChangeLog">CVS ChangeLog</A> going back to the beginning of the project.
393: Very technical information of varying quality, strictly chronological.
394: All commits are mentioned, but some messages neglect to mention some changes.
395: Partly terse, partly detailed and verbose. In any case, the ChangeLog is very long -
396: more than 25,000 lines, more than 700 kB.
397: </LI>
398: <LI>
399: <A HREF="/cgi-bin/cvsweb/?cvsroot=mdocml">CVS</A> web interface, going back to the beginning of the project.
400: Source code, diffs and commit messages for each source file. The real thing.
401: </LI>
402: </UL>
1.112 kristaps 403: <P CLASS="foot">
1.118 kristaps 404: <SMALL>
405: Copyright © 2008–2011
406: <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
1.154.2.4 schwarze 407: © 2013 Ingo Schwarze,
1.154.2.14! schwarze 408: $Date: 2013/11/07 22:09:54 $
1.118 kristaps 409: </SMALL>
1.112 kristaps 410: </P>
1.40 kristaps 411: </BODY>
412: </HTML>
CVSweb