Annotation of mandoc/index.sgml, Revision 1.115
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>
14: <A NAME="description">DESCRIPTION</A>
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>
42: <A NAME="sources">SOURCES</A>
43: </H1>
44:
45: <P>
46: <SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any UNIX system. The most current
1.114 kristaps 47: version is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>. If your system doesn't come
48: with <SPAN CLASS="nm">mdocml</SPAN> (see <Q>Downstream</Q>), run <CODE>make</CODE> to compile and <CODE>make
49: install</CODE> to install into <I>/usr/local</I>.
50: </P>
51: <P>
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
! 53: makewhatis</CODE> to build it.
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>
137: <A NAME="documentation">DOCUMENTATION</A>
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.115 ! kristaps 161: <TD VALIGN="top"><A HREF="mandoc.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.112 kristaps 173: <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
174: <TD VALIGN="top">
175: mandoc macro compiler library
176: <SMALL>
177: (<A HREF="mandoc.3.txt">text</A> |
178: <A HREF="mandoc.3.xhtml">xhtml</A> |
179: <A HREF="mandoc.3.pdf">pdf</A> |
180: <A HREF="mandoc.3.ps">postscript</A>)
181: </SMALL>
182: </TD>
183: </TR>
184: <TR>
185: <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
186: <TD VALIGN="top">
187: man language reference
188: <SMALL>
189: (<A HREF="man.7.txt">text</A> |
190: <A HREF="man.7.xhtml">xhtml</A> |
191: <A HREF="man.7.pdf">pdf</A> |
192: <A HREF="man.7.ps">postscript</A>)
193: </SMALL>
194: </TD>
195: </TR>
196: <TR>
197: <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
198: <TD VALIGN="top">
199: eqn-mandoc language reference
200: <SMALL>
201: (<A HREF="eqn.7.txt">text</A> |
202: <A HREF="eqn.7.xhtml">xhtml</A> |
203: <A HREF="eqn.7.pdf">pdf</A> |
204: <A HREF="eqn.7.ps">postscript</A>)
205: </SMALL>
206: </TD>
207: </TR>
208: <TR>
209: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
210: <TD VALIGN="top">
211: mandoc special characters
212: <SMALL>
213: (<A HREF="mandoc_char.7.txt">text</A> |
214: <A HREF="mandoc_char.7.xhtml">xhtml</A> |
215: <A HREF="mandoc_char.7.pdf">pdf</A> |
216: <A HREF="mandoc_char.7.ps">postscript</A>)
217: </SMALL>
218: </TD>
219: </TR>
220: <TR>
221: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
222: <TD VALIGN="top">
223: mdoc language reference
224: <SMALL>
225: (<A HREF="mdoc.7.txt">text</A> |
226: <A HREF="mdoc.7.xhtml">xhtml</A> |
227: <A HREF="mdoc.7.pdf">pdf</A> |
228: <A HREF="mdoc.7.ps">postscript</A>)
229: </SMALL>
230: </TD>
231: </TR>
232: <TR>
233: <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
234: <TD VALIGN="top">
235: roff-mandoc language reference
236: <SMALL>
237: (<A HREF="roff.7.txt">text</A> |
238: <A HREF="roff.7.xhtml">xhtml</A> |
239: <A HREF="roff.7.pdf">pdf</A> |
240: <A HREF="roff.7.ps">postscript</A>)
241: </SMALL>
242: </TD>
243: </TR>
244: <TR>
245: <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
246: <TD VALIGN="top">
247: tbl-mandoc language reference
248: <SMALL>
249: (<A HREF="tbl.7.txt">text</A> |
250: <A HREF="tbl.7.xhtml">xhtml</A> |
251: <A HREF="tbl.7.pdf">pdf</A> |
252: <A HREF="tbl.7.ps">postscript</A>)
253: </SMALL>
254: </TD>
255: </TR>
256: </TBODY>
257: </TABLE>
258:
259: <H1>
260: <A NAME="contact">CONTACT</A>
261: </H1>
262:
263: <P>
264: Use the mailing lists for bug-reports, patches, questions, etc. (these require subscription). Please check the
265: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
266: before posting. Beyond that, contact Kristaps at <A
267: HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
268: this e-mail address">kris...</A>@bsd.lv.
269: </P>
270:
271: <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
272: <COL WIDTH="175">
273: <COL>
274: <TBODY>
275: <TR>
276: <TD>
277: disc<A CLASS="external" TITLE="Reveal this e-mail address"
278: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
279: </TD>
280: <TD>
281: bug-reports, general questions, and announcements
282: <SMALL>(<A HREF="/archives/discuss/summary.html">archive</A>)</SMALL>
283: </TD>
284: </TR>
285: <TR>
286: <TD>
287: tec<A CLASS="external" TITLE="Reveal this e-mail address"
288: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
289: </TD>
290: <TD>
291: patches and system discussions
292: <SMALL>(<A HREF="/archives/tech/summary.html">archive</A>)</SMALL>
293: </TD>
294: </TR>
295: <TR>
296: <TD>
297: sou<A CLASS="external" TITLE="Reveal this e-mail address"
298: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
299: </TD>
300: <TD>
301: source commit messages
302: <SMALL>(<A HREF="/archives/source/summary.html">archive</A>)</SMALL>
303: </TD>
304: </TR>
305: </TBODY>
306: </TABLE>
307:
308: <H1>
309: <A NAME="news">NEWS</A>
310: </H1>
311:
312: <P CLASS="news">
1.115 ! kristaps 313: 12-05-2011: version 1.11.2
! 314: </P>
! 315: <P>
! 316: Corrected some installation issues in version 1.11.1.
! 317: Initial public release (this utility is very much under development) of <A HREF="makewhatis.1.html">makewhatis</A>,
! 318: initially named mandoc-db.
! 319: This utility produces keyword databases of manual content
! 320: <A HREF="http://mdocml.bsd.lv/mandoc-cgi/index.html">mandoc-cgi</A>, which features semantic querying of manual content.
! 321: </P>
! 322:
! 323: <P CLASS="news">
1.112 kristaps 324: 04-04-2011: version 1.11.1
325: </P>
326: <P>
327: The earlier <I>libroff</I>, <I>libmdoc</I>, and <I>libman</I> soup have been merged into
328: a single library, <A HREF="mandoc.3.html">libmandoc</A>, which manages all aspects of
329: parsing real manuals (from line-handling to <A HREF="tbl.7.html">tbl</A> parsing).
330: </P>
331: <P>
332: Beyond this structural change, initial <A HREF="eqn.7.html">eqn</A> functionality is in
333: place. For the time being, this is limited to the recognition of equation blocks;
334: future version of <SPAN CLASS="nm">mdocml</SPAN> will expand upon this framework.
335: </P>
336: <P>
1.113 kristaps 337: As usual, many general fixes and improvements have also occurred. In particular, a great
1.112 kristaps 338: deal of redundancy and superfluous code has been removed with the merging of the backend
339: libraries.
340: </P>
341:
342: <P CLASS="news">
343: 07-01-2011: version 1.10.9
344: </P>
345: <P>
346: Many back-end fixes have been implemented: argument handling (quoting), <A
347: HREF="man.7.html">man</A> improvements, error/warning classes, and many more.
348: </P>
349: <P>
350: Initial <A HREF="tbl.7.html">tbl</A> functionality (see the <Q>TS</Q>, <Q>TE</Q>, and
351: <Q>T&</Q> macros in the <A HREF="roff.7.html#x5c265453">roff</A> manual) has been
352: merged from <A CLASS="external" HREF="http://tbl.bsd.lv">tbl.bsd.lv</A>. Output is
353: still minimal, especially for <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
354: CLASS="flag">-Txhtml</SPAN>, but manages to at least display data. This means that <A
355: HREF="mandoc.1.html">mandoc</A> now has built-in support for two troff preprocessors via
356: <DEL>libroff</DEL>: soelim and tbl.
357: </P>
358:
359: <P CLASS="news">
360: 24-12-2010: version 1.10.8
361: </P>
362: <P>
363: Significant improvements merged from <A CLASS="external"
364: HREF="http://www.openbsd.org">OpenBSD</A> downstream, including
365: </P>
366: <UL>
367: <LI>many new <A HREF="roff.7.html">roff</A> components,</LI>
368: <LI>in-line implementation of troff's soelim,</LI>
369: <LI>broken-block handling,</LI>
370: <LI>overhauled error classifications, and</LI>
371: <LI>cleaned up handling of error conditions.</LI>
372: </UL>
373: <P>
374: Also overhauled the <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
375: CLASS="flag">-Txhtml</SPAN> output modes. They now display readable output in arbitrary
376: browsers, including text-based ones like <A CLASS="external"
377: HREF="http://lynx.isc.org">lynx</A>. See HTML and XHTML manuals in the <A
378: HREF="#documentation">DOCUMENTATION</A> section for examples. <SPAN
379: CLASS="attn">Attention: available style-sheet classes have been considerably
380: changed!</SPAN> See the <SPAN CLASS="file">example.style.css</SPAN> file for details.
381: Lastly, <DEL>libmdoc</DEL> and <DEL>libman</DEL> have been
382: cleaned up and reduced in size and complexity.
383: </P>
384:
385: <P>
386: See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
387: historical notes.
388: </P>
389:
390: <P CLASS="foot">
391: Copyright © 2008–2011
392: <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
1.115 ! kristaps 393: $Date: 2011/05/04 08:21:17 $
1.112 kristaps 394: </P>
1.40 kristaps 395: </BODY>
396: </HTML>
CVSweb