Annotation of mandoc/index.sgml, Revision 1.125
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: <H2>
58: Current
59: </H2>
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>
1.121 kristaps 68: <SMALL>(<A HREF="/snapshots/mdocml.md5">md5</A>)</SMALL>
1.112 kristaps 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: <H2>
80: Downstream
81: </H2>
82: <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
83: <COL WIDTH="175">
84: <COL>
85: <TBODY>
86: <TR>
87: <TD>DragonFly BSD</TD>
88: <TD>
89: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
90: CLASS="external">usr.bin/mandoc</A>
91: </TD>
92: </TR>
93: <TR>
94: <TD>FreeBSD</TD>
95: <TD>
96: <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
97: CLASS="external">ports/textproc/mdocml</A>
98: </TD>
99: </TR>
100: <TR>
101: <TD>NetBSD</TD>
102: <TD>
103: <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
104: CLASS="external">src/external/bsd/mdocml</A>
105: </TD>
106: </TR>
107: <TR>
108: <TD>OpenBSD</TD>
109: <TD>
110: <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
111: CLASS="external">src/usr.bin/mandoc</A>
112: </TD>
113: </TR>
114: </TBODY>
115: </TABLE>
116: <H2>
117: Historical
118: </H2>
119: <TABLE WIDTH="100%" SUMMARY="Archived Sources">
120: <COL WIDTH="175">
121: <COL>
122: <TBODY>
123: <TR>
124: <TD>Source archive</TD>
125: <TD>
126: <A HREF="/snapshots/">/snapshots/</A>
127: </TD>
128: </TR>
129: </TBODY>
130: </TABLE>
131: <H1>
1.118 kristaps 132: <A NAME="documentation">Documentation</A>
1.112 kristaps 133: </H1>
134: <P>
135: These manuals are generated automatically and refer to the current snapshot.
136: </P>
137:
138: <TABLE WIDTH="100%" SUMMARY="Documentation">
139: <COL WIDTH="175">
140: <COL>
141: <TBODY>
142: <TR>
143: <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
144: <TD VALIGN="top">
145: format and display UNIX manuals
146: <SMALL>
147: (<A HREF="mandoc.1.txt">text</A> |
148: <A HREF="mandoc.1.xhtml">xhtml</A> |
149: <A HREF="mandoc.1.pdf">pdf</A> |
150: <A HREF="mandoc.1.ps">postscript</A>)
151: </SMALL>
152: </TD>
153: </TR>
154: <TR>
1.117 kristaps 155: <TD VALIGN="top"><A HREF="makewhatis.1.html">makewhatis(1)</A></TD>
1.114 kristaps 156: <TD VALIGN="top">
157: index UNIX manuals
158: <SMALL>
1.115 kristaps 159: (<A HREF="makewhatis.1.txt">text</A> |
160: <A HREF="makewhatis.1.xhtml">xhtml</A> |
161: <A HREF="makewhatis.1.pdf">pdf</A> |
162: <A HREF="makewhatis.1.ps">postscript</A>)
1.114 kristaps 163: </SMALL>
164: </TD>
165: </TR>
166: <TR>
1.120 kristaps 167: <TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD>
168: <TD VALIGN="top">
169: recode multibyte UNIX manuals
170: <SMALL>
171: (<A HREF="preconv.1.txt">text</A> |
172: <A HREF="preconv.1.xhtml">xhtml</A> |
173: <A HREF="preconv.1.pdf">pdf</A> |
174: <A HREF="preconv.1.ps">postscript</A>)
175: </SMALL>
176: </TD>
177: </TR>
178: <TR>
1.112 kristaps 179: <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
180: <TD VALIGN="top">
181: mandoc macro compiler library
182: <SMALL>
183: (<A HREF="mandoc.3.txt">text</A> |
184: <A HREF="mandoc.3.xhtml">xhtml</A> |
185: <A HREF="mandoc.3.pdf">pdf</A> |
186: <A HREF="mandoc.3.ps">postscript</A>)
187: </SMALL>
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
194: <SMALL>
195: (<A HREF="man.7.txt">text</A> |
196: <A HREF="man.7.xhtml">xhtml</A> |
197: <A HREF="man.7.pdf">pdf</A> |
198: <A HREF="man.7.ps">postscript</A>)
199: </SMALL>
200: </TD>
201: </TR>
202: <TR>
203: <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
204: <TD VALIGN="top">
205: eqn-mandoc language reference
206: <SMALL>
207: (<A HREF="eqn.7.txt">text</A> |
208: <A HREF="eqn.7.xhtml">xhtml</A> |
209: <A HREF="eqn.7.pdf">pdf</A> |
210: <A HREF="eqn.7.ps">postscript</A>)
211: </SMALL>
212: </TD>
213: </TR>
214: <TR>
215: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
216: <TD VALIGN="top">
217: mandoc special characters
218: <SMALL>
219: (<A HREF="mandoc_char.7.txt">text</A> |
220: <A HREF="mandoc_char.7.xhtml">xhtml</A> |
221: <A HREF="mandoc_char.7.pdf">pdf</A> |
222: <A HREF="mandoc_char.7.ps">postscript</A>)
223: </SMALL>
224: </TD>
225: </TR>
226: <TR>
227: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
228: <TD VALIGN="top">
229: mdoc language reference
230: <SMALL>
231: (<A HREF="mdoc.7.txt">text</A> |
232: <A HREF="mdoc.7.xhtml">xhtml</A> |
233: <A HREF="mdoc.7.pdf">pdf</A> |
234: <A HREF="mdoc.7.ps">postscript</A>)
235: </SMALL>
236: </TD>
237: </TR>
238: <TR>
239: <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
240: <TD VALIGN="top">
241: roff-mandoc language reference
242: <SMALL>
243: (<A HREF="roff.7.txt">text</A> |
244: <A HREF="roff.7.xhtml">xhtml</A> |
245: <A HREF="roff.7.pdf">pdf</A> |
246: <A HREF="roff.7.ps">postscript</A>)
247: </SMALL>
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
254: <SMALL>
255: (<A HREF="tbl.7.txt">text</A> |
256: <A HREF="tbl.7.xhtml">xhtml</A> |
257: <A HREF="tbl.7.pdf">pdf</A> |
258: <A HREF="tbl.7.ps">postscript</A>)
259: </SMALL>
260: </TD>
261: </TR>
262: </TBODY>
263: </TABLE>
264: <H1>
1.118 kristaps 265: <A NAME="contact">Contact</A>
1.112 kristaps 266: </H1>
267: <P>
268: Use the mailing lists for bug-reports, patches, questions, etc. (these require subscription). Please check the
269: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
270: before posting. Beyond that, contact Kristaps at <A
271: HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
272: this e-mail address">kris...</A>@bsd.lv.
273: </P>
274: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
275: <COL WIDTH="175">
276: <COL>
277: <TBODY>
278: <TR>
279: <TD>
280: disc<A CLASS="external" TITLE="Reveal this e-mail address"
281: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
282: </TD>
283: <TD>
284: bug-reports, general questions, and announcements
285: <SMALL>(<A HREF="/archives/discuss/summary.html">archive</A>)</SMALL>
286: </TD>
287: </TR>
288: <TR>
289: <TD>
290: tec<A CLASS="external" TITLE="Reveal this e-mail address"
291: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
292: </TD>
293: <TD>
294: patches and system discussions
295: <SMALL>(<A HREF="/archives/tech/summary.html">archive</A>)</SMALL>
296: </TD>
297: </TR>
298: <TR>
299: <TD>
300: sou<A CLASS="external" TITLE="Reveal this e-mail address"
301: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
302: </TD>
303: <TD>
304: source commit messages
305: <SMALL>(<A HREF="/archives/source/summary.html">archive</A>)</SMALL>
306: </TD>
307: </TR>
308: </TBODY>
309: </TABLE>
310: <H1>
1.118 kristaps 311: <A NAME="news">News</A>
1.112 kristaps 312: </H1>
1.124 kristaps 313: <P CLASS="news">
1.125 ! kristaps 314: 12-07-2011: version 1.11.4
1.124 kristaps 315: </P>
316: <P>
317: Bug-fixes and clean-ups across all systems, especially in <A HREF="makewhatis.1.html">makewhatis</A> (note: still not
1.125 ! kristaps 318: connected to the general build and must be compiled with <CODE>make makewhatis</CODE>) and the <A
! 319: HREF="man.7.html">man</A> parser. This release was significantly assisted by participants in <A CLASS="external"
! 320: HREF="http://www.openbsd.org">OpenBSD</A>'s c2k11. Thanks!
1.124 kristaps 321: </P>
1.112 kristaps 322: <P CLASS="news">
1.122 kristaps 323: 26-05-2011: version 1.11.3
1.119 kristaps 324: </P>
325: <P>
326: Introduce locale-encoding of output with the <B>-Tlocale</B> output option and Unicode escaped-character input.
327: See <A HREF="mandoc.1.html">mandoc</A> and <A HREF="mandoc_char.7.html">mandoc_char</A>, respectively, for details.
328: This allows for non-ASCII characters (e.g., <I>\[u5000]</I>) to be rendered in the locale's encoding, if said
329: environment supports wide-character encoding (if it does not, <B>-Tascii</B> is used instead).
330: Locale support can be turned off at compile time by removing <I>-DUSE_WCHAR</I> in the <I>Makefile</I>, in which case
331: <B>-Tlocale</B> is always a synonym for <B>-Tascii</B>.
332: </P>
1.120 kristaps 333: <P>
1.122 kristaps 334: Furthermore, multibyte-encoded documents, such as those in UTF-8, may be on-the-fly recoded into <A
1.120 kristaps 335: HREF="mandoc.1.html">mandoc</A> input by using the newly-added <A HREF="preconv.1.html">preconv</A> utility.
1.121 kristaps 336: Note: in the future, this feature may be integrated into <A HREF="mandoc.1.html">mandoc</A>.
1.120 kristaps 337: </P>
1.119 kristaps 338: <P CLASS="news">
1.115 kristaps 339: 12-05-2011: version 1.11.2
340: </P>
341: <P>
342: Corrected some installation issues in version 1.11.1.
1.116 kristaps 343: Further migration to <A HREF="mandoc.3.html">libmandoc</A>.
1.115 kristaps 344: Initial public release (this utility is very much under development) of <A HREF="makewhatis.1.html">makewhatis</A>,
345: initially named mandoc-db.
346: This utility produces keyword databases of manual content
1.123 kristaps 347: <STRIKE>mandoc-cgi</STRIKE>,
348: <A HREF="http://mdocml.bsd.lv/mandoc-tools/index.html">mandoc-tools</A>,
349: which features semantic querying of manual content.
1.115 kristaps 350: </P>
1.112 kristaps 351: <P>
352: See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
353: historical notes.
354: </P>
355: <P CLASS="foot">
1.118 kristaps 356: <SMALL>
357: Copyright © 2008–2011
358: <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
1.125 ! kristaps 359: $Date: 2011/07/01 10:20:26 $
1.118 kristaps 360: </SMALL>
1.112 kristaps 361: </P>
1.40 kristaps 362: </BODY>
363: </HTML>
CVSweb