Annotation of mandoc/index.sgml, Revision 1.133
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.47 kristaps 6: <TITLE>mdocml | mdoc macro compiler</TITLE>
1.40 kristaps 7: </HEAD>
8: <BODY>
1.112 kristaps 9: <P CLASS="head">
10: <B>mdocml</B> – mdoc macro compiler
11: </P>
12: <H1>
1.118 kristaps 13: <A NAME="description">Description</A>
1.112 kristaps 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
1.121 kristaps 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
1.128 schwarze 32: HREF="mandocdb.8.html">mandocdb</A>, for indexing manuals.
1.121 kristaps 33: It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.
1.112 kristaps 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>
1.118 kristaps 39: <A NAME="sources">Sources</A>
1.112 kristaps 40: </H1>
41: <P>
1.132 kristaps 42: <SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any modern system (<A
1.128 schwarze 43: HREF="mandocdb.8.html">mandocdb</A> requires <A CLASS="external"
1.132 kristaps 44: HREF="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">Berkeley Database</A>, installed by
45: default on all BSD UNIX operating systems).
46: </P>
47: <P>
1.121 kristaps 48: To compile <SPAN CLASS="nm">mdocml</SPAN>, run <CODE>make</CODE>, then <CODE>make install</CODE> to install into
1.132 kristaps 49: <I>/usr/local</I>. Be aware: if you have an existing <A HREF="http://www.gnu.org/software/groff/"
50: CLASS="external">groff</A> installation, this may overwrite its <B>preconv</B> binary. The <A
51: HREF="mandocdb.8.html">mandocdb</A> utility is not yet linked to the build: you must run <CODE>make mandocdb</CODE> to
52: build it (it does not install).
53: </P>
54: <P>
55: Distributed Win32 binaries are compiled using <A CLASS="external" HREF="http://www.mingw.org/">mingw32</A>. They are
56: distributed in a ZIP archive consisting of binaries, manuals, and other installable media.
1.112 kristaps 57: </P>
1.121 kristaps 58: <P>
59: The most current version of <SPAN CLASS="nm">mdocml</SPAN> is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN
60: class="attn">@VDATE@</SPAN>.
61: </P>
1.112 kristaps 62: <H2>
63: Current
64: </H2>
65: <TABLE WIDTH="100%" SUMMARY="Current Sources">
66: <COL WIDTH="175">
67: <COL>
68: <TBODY>
69: <TR>
70: <TD>Source archive</TD>
71: <TD>
72: <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
1.121 kristaps 73: <SMALL>(<A HREF="/snapshots/mdocml.md5">md5</A>)</SMALL>
1.112 kristaps 74: </TD>
75: </TR>
76: <TR>
77: <TD>Online source</TD>
78: <TD>
79: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
80: </TD>
81: </TR>
1.132 kristaps 82: <TR>
83: <TD>Win32 binary archive</TD>
84: <TD>
1.133 ! kristaps 85: <A HREF="/binaries/mdocml-win32.zip">/binaries/mdocml-win32.zip</A>
1.132 kristaps 86: </TD>
87: </TR>
1.112 kristaps 88: </TBODY>
89: </TABLE>
90: <H2>
91: Downstream
92: </H2>
93: <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
94: <COL WIDTH="175">
95: <COL>
96: <TBODY>
97: <TR>
98: <TD>DragonFly BSD</TD>
99: <TD>
100: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
101: CLASS="external">usr.bin/mandoc</A>
102: </TD>
103: </TR>
104: <TR>
105: <TD>FreeBSD</TD>
106: <TD>
107: <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
108: CLASS="external">ports/textproc/mdocml</A>
109: </TD>
110: </TR>
111: <TR>
112: <TD>NetBSD</TD>
113: <TD>
114: <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
115: CLASS="external">src/external/bsd/mdocml</A>
116: </TD>
117: </TR>
118: <TR>
119: <TD>OpenBSD</TD>
120: <TD>
121: <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
122: CLASS="external">src/usr.bin/mandoc</A>
123: </TD>
124: </TR>
125: </TBODY>
126: </TABLE>
127: <H2>
128: Historical
129: </H2>
130: <TABLE WIDTH="100%" SUMMARY="Archived Sources">
131: <COL WIDTH="175">
132: <COL>
133: <TBODY>
134: <TR>
135: <TD>Source archive</TD>
136: <TD>
137: <A HREF="/snapshots/">/snapshots/</A>
138: </TD>
139: </TR>
1.132 kristaps 140: <TR>
141: <TD>Binary archive</TD>
142: <TD>
143: <A HREF="/binaries/">/binaries/</A>
144: </TD>
145: </TR>
1.112 kristaps 146: </TBODY>
147: </TABLE>
148: <H1>
1.118 kristaps 149: <A NAME="documentation">Documentation</A>
1.112 kristaps 150: </H1>
151: <P>
152: These manuals are generated automatically and refer to the current snapshot.
153: </P>
154:
155: <TABLE WIDTH="100%" SUMMARY="Documentation">
156: <COL WIDTH="175">
157: <COL>
158: <TBODY>
159: <TR>
160: <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
161: <TD VALIGN="top">
162: format and display UNIX manuals
163: <SMALL>
164: (<A HREF="mandoc.1.txt">text</A> |
165: <A HREF="mandoc.1.xhtml">xhtml</A> |
166: <A HREF="mandoc.1.pdf">pdf</A> |
167: <A HREF="mandoc.1.ps">postscript</A>)
168: </SMALL>
169: </TD>
170: </TR>
171: <TR>
1.128 schwarze 172: <TD VALIGN="top"><A HREF="mandocdb.8.html">mandocdb(8)</A></TD>
1.114 kristaps 173: <TD VALIGN="top">
174: index UNIX manuals
175: <SMALL>
1.128 schwarze 176: (<A HREF="mandocdb.8.txt">text</A> |
177: <A HREF="mandocdb.8.xhtml">xhtml</A> |
178: <A HREF="mandocdb.8.pdf">pdf</A> |
179: <A HREF="mandocdb.8.ps">postscript</A>)
1.114 kristaps 180: </SMALL>
181: </TD>
182: </TR>
183: <TR>
1.120 kristaps 184: <TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD>
185: <TD VALIGN="top">
186: recode multibyte UNIX manuals
187: <SMALL>
188: (<A HREF="preconv.1.txt">text</A> |
189: <A HREF="preconv.1.xhtml">xhtml</A> |
190: <A HREF="preconv.1.pdf">pdf</A> |
191: <A HREF="preconv.1.ps">postscript</A>)
192: </SMALL>
193: </TD>
194: </TR>
195: <TR>
1.112 kristaps 196: <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
197: <TD VALIGN="top">
198: mandoc macro compiler library
199: <SMALL>
200: (<A HREF="mandoc.3.txt">text</A> |
201: <A HREF="mandoc.3.xhtml">xhtml</A> |
202: <A HREF="mandoc.3.pdf">pdf</A> |
203: <A HREF="mandoc.3.ps">postscript</A>)
204: </SMALL>
205: </TD>
206: </TR>
207: <TR>
208: <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
209: <TD VALIGN="top">
210: man language reference
211: <SMALL>
212: (<A HREF="man.7.txt">text</A> |
213: <A HREF="man.7.xhtml">xhtml</A> |
214: <A HREF="man.7.pdf">pdf</A> |
215: <A HREF="man.7.ps">postscript</A>)
216: </SMALL>
217: </TD>
218: </TR>
219: <TR>
220: <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
221: <TD VALIGN="top">
222: eqn-mandoc language reference
223: <SMALL>
224: (<A HREF="eqn.7.txt">text</A> |
225: <A HREF="eqn.7.xhtml">xhtml</A> |
226: <A HREF="eqn.7.pdf">pdf</A> |
227: <A HREF="eqn.7.ps">postscript</A>)
228: </SMALL>
229: </TD>
230: </TR>
231: <TR>
232: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
233: <TD VALIGN="top">
234: mandoc special characters
235: <SMALL>
236: (<A HREF="mandoc_char.7.txt">text</A> |
237: <A HREF="mandoc_char.7.xhtml">xhtml</A> |
238: <A HREF="mandoc_char.7.pdf">pdf</A> |
239: <A HREF="mandoc_char.7.ps">postscript</A>)
240: </SMALL>
241: </TD>
242: </TR>
243: <TR>
244: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
245: <TD VALIGN="top">
246: mdoc language reference
247: <SMALL>
248: (<A HREF="mdoc.7.txt">text</A> |
249: <A HREF="mdoc.7.xhtml">xhtml</A> |
250: <A HREF="mdoc.7.pdf">pdf</A> |
251: <A HREF="mdoc.7.ps">postscript</A>)
252: </SMALL>
253: </TD>
254: </TR>
255: <TR>
256: <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
257: <TD VALIGN="top">
258: roff-mandoc language reference
259: <SMALL>
260: (<A HREF="roff.7.txt">text</A> |
261: <A HREF="roff.7.xhtml">xhtml</A> |
262: <A HREF="roff.7.pdf">pdf</A> |
263: <A HREF="roff.7.ps">postscript</A>)
264: </SMALL>
265: </TD>
266: </TR>
267: <TR>
268: <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
269: <TD VALIGN="top">
270: tbl-mandoc language reference
271: <SMALL>
272: (<A HREF="tbl.7.txt">text</A> |
273: <A HREF="tbl.7.xhtml">xhtml</A> |
274: <A HREF="tbl.7.pdf">pdf</A> |
275: <A HREF="tbl.7.ps">postscript</A>)
276: </SMALL>
277: </TD>
278: </TR>
279: </TBODY>
280: </TABLE>
281: <H1>
1.118 kristaps 282: <A NAME="contact">Contact</A>
1.112 kristaps 283: </H1>
284: <P>
285: Use the mailing lists for bug-reports, patches, questions, etc. (these require subscription). Please check the
286: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
287: before posting. Beyond that, contact Kristaps at <A
288: HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
289: this e-mail address">kris...</A>@bsd.lv.
290: </P>
291: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
292: <COL WIDTH="175">
293: <COL>
294: <TBODY>
295: <TR>
296: <TD>
297: disc<A CLASS="external" TITLE="Reveal this e-mail address"
298: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
299: </TD>
300: <TD>
301: bug-reports, general questions, and announcements
302: <SMALL>(<A HREF="/archives/discuss/summary.html">archive</A>)</SMALL>
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==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
309: </TD>
310: <TD>
311: patches and system discussions
312: <SMALL>(<A HREF="/archives/tech/summary.html">archive</A>)</SMALL>
313: </TD>
314: </TR>
315: <TR>
316: <TD>
317: sou<A CLASS="external" TITLE="Reveal this e-mail address"
318: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
319: </TD>
320: <TD>
321: source commit messages
322: <SMALL>(<A HREF="/archives/source/summary.html">archive</A>)</SMALL>
323: </TD>
324: </TR>
325: </TBODY>
326: </TABLE>
327: <H1>
1.118 kristaps 328: <A NAME="news">News</A>
1.112 kristaps 329: </H1>
1.124 kristaps 330: <P CLASS="news">
1.131 kristaps 331: 24-07-2011: version 1.11.5
1.129 kristaps 332: </P>
333: <P>
1.130 kristaps 334: Significant <A HREF="eqn.7.html">eqn</A> improvements. <SPAN CLASS="nm">mdocml</SPAN> can now parse arbitrary eqn input
335: (although few GNU extensions are accepted, nor is mixing low-level roff with eqn). See the <A HREF="eqn.7.html">eqn</A>
336: manual for details. For the time being, equations are rendered as simple in-line text. The equation parser satisfies
337: the language specified in the <A CLASS="external" HREF="http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps">Second
1.131 kristaps 338: Edition User's Guide</A>.
1.129 kristaps 339: </P>
1.132 kristaps 340: <P>
341: This is also the first release featuring a distributed Windows binary, available at <A
342: HREF="/binaries/mdocml-win32.zip">/binaries/mdocml-win32.zip</A>.
343: </P>
1.129 kristaps 344: <P CLASS="news">
1.125 kristaps 345: 12-07-2011: version 1.11.4
1.124 kristaps 346: </P>
347: <P>
1.128 schwarze 348: Bug-fixes and clean-ups across all systems, especially in <INS><A HREF="mandocdb.8.html">mandocdb</A></INS> <DEL>makewhatis</DEL> (note: still not
1.127 kristaps 349: connected to the general build and must be compiled with <INS><CODE>make mandocdb</CODE></INS> <DEL><CODE>make makewhatis</CODE></DEL>) and the <A
1.125 kristaps 350: HREF="man.7.html">man</A> parser. This release was significantly assisted by participants in <A CLASS="external"
351: HREF="http://www.openbsd.org">OpenBSD</A>'s c2k11. Thanks!
1.124 kristaps 352: </P>
1.112 kristaps 353: <P CLASS="news">
1.122 kristaps 354: 26-05-2011: version 1.11.3
1.119 kristaps 355: </P>
356: <P>
357: Introduce locale-encoding of output with the <B>-Tlocale</B> output option and Unicode escaped-character input.
358: See <A HREF="mandoc.1.html">mandoc</A> and <A HREF="mandoc_char.7.html">mandoc_char</A>, respectively, for details.
359: This allows for non-ASCII characters (e.g., <I>\[u5000]</I>) to be rendered in the locale's encoding, if said
360: environment supports wide-character encoding (if it does not, <B>-Tascii</B> is used instead).
361: Locale support can be turned off at compile time by removing <I>-DUSE_WCHAR</I> in the <I>Makefile</I>, in which case
362: <B>-Tlocale</B> is always a synonym for <B>-Tascii</B>.
363: </P>
1.120 kristaps 364: <P>
1.122 kristaps 365: Furthermore, multibyte-encoded documents, such as those in UTF-8, may be on-the-fly recoded into <A
1.120 kristaps 366: HREF="mandoc.1.html">mandoc</A> input by using the newly-added <A HREF="preconv.1.html">preconv</A> utility.
1.121 kristaps 367: Note: in the future, this feature may be integrated into <A HREF="mandoc.1.html">mandoc</A>.
1.120 kristaps 368: </P>
1.119 kristaps 369: <P CLASS="news">
1.115 kristaps 370: 12-05-2011: version 1.11.2
371: </P>
372: <P>
373: Corrected some installation issues in version 1.11.1.
1.116 kristaps 374: Further migration to <A HREF="mandoc.3.html">libmandoc</A>.
1.128 schwarze 375: Initial public release (this utility is very much under development) of <INS><A HREF="mandocdb.8.html">mandocdb</A></INS><DEL>makewhatis</DEL>,
1.115 kristaps 376: initially named mandoc-db.
377: This utility produces keyword databases of manual content
1.126 kristaps 378: <DEL>mandoc-cgi</DEL>,
1.123 kristaps 379: <A HREF="http://mdocml.bsd.lv/mandoc-tools/index.html">mandoc-tools</A>,
380: which features semantic querying of manual content.
1.115 kristaps 381: </P>
1.112 kristaps 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: <P CLASS="foot">
1.118 kristaps 387: <SMALL>
388: Copyright © 2008–2011
389: <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
1.133 ! kristaps 390: $Date: 2011/07/24 19:03:40 $
1.118 kristaps 391: </SMALL>
1.112 kristaps 392: </P>
1.40 kristaps 393: </BODY>
394: </HTML>
CVSweb