Annotation of mandoc/index.sgml, Revision 1.122
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
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.
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.118 kristaps 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
1.121 kristaps 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
1.118 kristaps 51: makewhatis</CODE> to build it (it does not install).
1.112 kristaps 52: </P>
1.121 kristaps 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>
1.112 kristaps 57:
58: <H2>
59: Current
60: </H2>
61:
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>
1.121 kristaps 70: <SMALL>(<A HREF="/snapshots/mdocml.md5">md5</A>)</SMALL>
1.112 kristaps 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>
81:
82: <H2>
83: Downstream
84: </H2>
85:
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>
120:
121: <H2>
122: Historical
123: </H2>
124:
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>
137:
138: <H1>
1.118 kristaps 139: <A NAME="documentation">Documentation</A>
1.112 kristaps 140: </H1>
141:
142: <P>
143: These manuals are generated automatically and refer to the current snapshot.
144: </P>
145:
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>
1.117 kristaps 163: <TD VALIGN="top"><A HREF="makewhatis.1.html">makewhatis(1)</A></TD>
1.114 kristaps 164: <TD VALIGN="top">
165: index UNIX manuals
166: <SMALL>
1.115 kristaps 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>)
1.114 kristaps 171: </SMALL>
172: </TD>
173: </TR>
174: <TR>
1.120 kristaps 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>
1.112 kristaps 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>
272:
273: <H1>
1.118 kristaps 274: <A NAME="contact">Contact</A>
1.112 kristaps 275: </H1>
276:
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==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
282: this e-mail address">kris...</A>@bsd.lv.
283: </P>
284:
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==&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==&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==&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>
321:
322: <H1>
1.118 kristaps 323: <A NAME="news">News</A>
1.112 kristaps 324: </H1>
325:
326: <P CLASS="news">
1.122 ! kristaps 327: 26-05-2011: version 1.11.3
1.119 kristaps 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>
1.120 kristaps 337: <P>
1.122 ! kristaps 338: Furthermore, multibyte-encoded documents, such as those in UTF-8, may be on-the-fly recoded into <A
1.120 kristaps 339: HREF="mandoc.1.html">mandoc</A> input by using the newly-added <A HREF="preconv.1.html">preconv</A> utility.
1.121 kristaps 340: Note: in the future, this feature may be integrated into <A HREF="mandoc.1.html">mandoc</A>.
1.120 kristaps 341: </P>
1.119 kristaps 342:
343: <P CLASS="news">
1.115 kristaps 344: 12-05-2011: version 1.11.2
345: </P>
346: <P>
347: Corrected some installation issues in version 1.11.1.
1.116 kristaps 348: Further migration to <A HREF="mandoc.3.html">libmandoc</A>.
1.115 kristaps 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>
354:
355: <P CLASS="news">
1.112 kristaps 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>
1.113 kristaps 369: As usual, many general fixes and improvements have also occurred. In particular, a great
1.112 kristaps 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">
1.118 kristaps 380: <SMALL>
381: Copyright © 2008–2011
382: <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
1.122 ! kristaps 383: $Date: 2011/05/26 20:23:01 $
1.118 kristaps 384: </SMALL>
1.112 kristaps 385: </P>
1.40 kristaps 386: </BODY>
387: </HTML>
CVSweb