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