Return to index.sgml CVS log | Up to [cvsweb.bsd.lv] / mandoc |
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.149 kristaps 6: <TITLE>mdocml | UNIX manpage compiler</TITLE> 1.40 kristaps 7: </HEAD> 8: <BODY> 1.112 kristaps 9: <P CLASS="head"> 1.149 kristaps 10: <B>mdocml</B> – UNIX manpage compiler, current version @VERSION@ (@VDATE@) 1.136 kristaps 11: </P> 12: <P CLASS="subhead"> 13: Sources: <A HREF="/snapshots/mdocml.tar.gz">current</A>, 14: <A HREF="/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> 15: (<A HREF="/snapshots/">archives</A>) 1.112 kristaps 16: </P> 17: <H1> 1.118 kristaps 18: <A NAME="description">Description</A> 1.112 kristaps 19: </H1> 20: <P> 21: <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <I><A HREF="mdoc.7.html">mdoc</A></I>, the roff macro 22: package of choice for BSD manual pages, and <I><A HREF="man.7.html">man</A></I>, the predominant historical package for 23: UNIX manuals. The mission of <SPAN CLASS="nm">mdocml</SPAN> is to deprecate <A 24: HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU troff implementation, for displaying <I>mdoc</I> 25: pages whilst providing token support for <I>man</I>. 26: </P> 27: <P> 1.154.2.4 schwarze 28: Why? groff amounts to over 5 MB of source code, most of which is C++ and GPL version 3. It runs slowly, produces 1.112 kristaps 29: uncertain output, and varies in operation from system to system. mdocml strives to fix this (respectively small, C, <A 30: CLASS="external" HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular). 31: </P> 32: <P> 33: <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating compiler and <A 1.121 kristaps 34: HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format output for UNIX terminals (with 35: support for wide-character locales), XHTML, HTML, PostScript, and PDF. 1.138 kristaps 36: It also includes <A HREF="preconv.1.html">preconv</A>, for recoding multibyte manuals; 37: <A HREF="demandoc.1.html">demandoc</A>, for emitting only text parts of manuals; 1.144 kristaps 38: <A HREF="mandocdb.8.html">mandocdb</A>, for indexing manuals; and 1.150 kristaps 39: <A HREF="apropos.1.html">apropos</A>, <A HREF="whatis.1.html">whatis</A>, and 40: <A HREF="man.cgi.7.html">man.cgi</A> (via <A HREF="catman.8.html">catman</A>) for semantic search of manual content. 1.121 kristaps 41: It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project. 1.112 kristaps 42: </P> 43: <P> 44: <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary, <Q>mandoc</Q>. 45: </P> 1.137 kristaps 46: <H2> 1.118 kristaps 47: <A NAME="sources">Sources</A> 1.137 kristaps 48: </H2> 1.112 kristaps 49: <P> 1.145 kristaps 50: <SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any modern system; however, you'll 51: need <A HREF="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">libdb</A> to build <A 1.150 kristaps 52: HREF="apropos.1.html">apropos</A>, <A HREF="whatis.1.html">whatis</A>, <A HREF="man.cgi.7.html">man.cgi</A>, <A 53: HREF="catman.8.html">catman</A>, and <A HREF="mandocdb.8.html">mandocdb</A> (this is installed by default on BSD UNIX 54: systems — see the <I>Makefile</I> if you're running Linux). To build and install into <I>/usr/local/</I>, just 55: run <CODE>make install</CODE>. Be careful: the <B>preconv</B>, <B>apropos</B>, and <B>whatis</B> binary names are 56: usually taken by existing utilities. 1.132 kristaps 57: </P> 1.137 kristaps 58: <H2> 1.112 kristaps 59: Downstream 1.137 kristaps 60: </H2> 1.135 kristaps 61: <P> 62: Several systems come bundled with <SPAN CLASS="nm">mdocml</SPAN> utilities. 63: If your system does not appear below, the maintainers have not contacted me and it should not be considered 64: <Q>official</Q>. 65: Please <A HREF="#contact">contact us</A> if you plan on maintaining a downstream version! 66: </P> 1.112 kristaps 67: <TABLE WIDTH="100%" SUMMARY="Downstream Sources"> 1.136 kristaps 68: <COL WIDTH="175"> 1.112 kristaps 69: <COL> 70: <TBODY> 71: <TR> 72: <TD>DragonFly BSD</TD> 73: <TD> 1.154.2.9 schwarze 74: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/contrib/mdocml" CLASS="external">contrib/mdocml</A> (1.12.2 sources) 1.154.2.4 schwarze 75: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/lib/libmandoc" CLASS="external">lib/libmandoc</A> 76: <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc" CLASS="external">usr.bin/mandoc</A> (build system) 1.112 kristaps 77: </TD> 78: </TR> 79: <TR> 1.154.2.5 schwarze 80: <TD>FreeBSD 10.0, -CURRENT</TD> 1.112 kristaps 81: <TD> 1.154.2.5 schwarze 82: <A HREF="http://svnweb.freebsd.org/base/head/contrib/mdocml/" CLASS="external">contrib/mdocml</A> (1.12.1 sources) 83: <A HREF="http://svnweb.freebsd.org/base/head/usr.bin/mandoc/" CLASS="external">usr.bin/mandoc</A> (build system) 84: </TD> 85: </TR> 86: <TR> 87: <TD>FreeBSD 9.x, 8.x</TD> 88: <TD> 1.154.2.8 schwarze 89: <A HREF="http://svnweb.freebsd.org/ports/head/textproc/mdocml/" CLASS="external">ports/textproc/mdocml</A> (1.12.1 port) 1.112 kristaps 90: </TD> 91: </TR> 92: <TR> 93: <TD>NetBSD</TD> 94: <TD> 1.154.2.4 schwarze 95: <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/" CLASS="external">src/external/bsd/mdocml</A> (1.12.1 sources plus patches and build system) 1.112 kristaps 96: </TD> 97: </TR> 98: <TR> 99: <TD>OpenBSD</TD> 100: <TD> 1.154.2.4 schwarze 101: <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/" CLASS="external">src/usr.bin/mandoc</A> (1.12.2 sources and build system) 1.112 kristaps 102: </TD> 103: </TR> 1.148 kristaps 104: <TR> 105: <TD>pkgsrc</TD> 106: <TD> 1.154.2.8 schwarze 107: <A HREF="http://pkgsrc.se/textproc/mdocml" CLASS="external">textproc/mdocml</A> (1.12.2 port) 1.148 kristaps 108: </TD> 109: </TR> 1.153 kristaps 110: <TR> 111: <TD>Minix3</TD> 112: <TD> 1.154.2.4 schwarze 113: <A HREF="http://git.minix3.org/?p=minix.git;a=tree;f=external/bsd/mdocml" CLASS="external">external/bsd/mdocml</A> (1.10.9 sources and build system) 1.153 kristaps 114: </TD> 115: </TR> 1.154.2.6 schwarze 116: <TR> 117: <TD>Alpine Linux</TD> 118: <TD> 1.154.2.10! schwarze 119: <A HREF="http://git.alpinelinux.org/cgit/aports/tree/main/mdocml" CLASS="external">aports/main/mdocml</A> (1.12.2 port) 1.154.2.6 schwarze 120: </TD> 121: </TR> 1.112 kristaps 122: </TBODY> 123: </TABLE> 124: <H1> 1.118 kristaps 125: <A NAME="documentation">Documentation</A> 1.112 kristaps 126: </H1> 127: <P> 1.135 kristaps 128: These manuals are generated automatically and refer to the current release. 129: They are the authoritative documentation for the <SPAN CLASS="nm">mdocml</SPAN> system. 1.112 kristaps 130: </P> 131: 132: <TABLE WIDTH="100%" SUMMARY="Documentation"> 1.136 kristaps 133: <COL WIDTH="175"> 1.112 kristaps 134: <COL> 135: <TBODY> 136: <TR> 1.144 kristaps 137: <TD VALIGN="top"><A HREF="apropos.1.html">apropos(1)</A></TD> 1.112 kristaps 138: <TD VALIGN="top"> 1.144 kristaps 139: search the manual page database 1.112 kristaps 140: </TD> 141: </TR> 142: <TR> 1.138 kristaps 143: <TD VALIGN="top"><A HREF="demandoc.1.html">demandoc(1)</A></TD> 1.114 kristaps 144: <TD VALIGN="top"> 1.138 kristaps 145: emit only text of UNIX manuals 1.114 kristaps 146: </TD> 147: </TR> 148: <TR> 1.144 kristaps 149: <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD> 150: <TD VALIGN="top"> 151: format and display UNIX manuals 152: </TD> 153: </TR> 154: <TR> 1.120 kristaps 155: <TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD> 156: <TD VALIGN="top"> 157: recode multibyte UNIX manuals 158: </TD> 159: </TR> 160: <TR> 1.149 kristaps 161: <TD VALIGN="top"><A HREF="whatis.1.html">whatis(1)</A></TD> 162: <TD VALIGN="top"> 163: search the manual page database 164: </TD> 165: </TR> 166: <TR> 1.112 kristaps 167: <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD> 168: <TD VALIGN="top"> 169: mandoc macro compiler library 170: </TD> 171: </TR> 172: <TR> 1.154.2.2 schwarze 173: <TD VALIGN="top"><A HREF="tbl.3.html">tbl(3)</A></TD> 174: <TD VALIGN="top"> 175: roff table parser library for mandoc 176: </TD> 177: </TR> 178: <TR> 1.154.2.4 schwarze 179: <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD> 1.112 kristaps 180: <TD VALIGN="top"> 1.154.2.4 schwarze 181: eqn-mandoc language reference 1.112 kristaps 182: </TD> 183: </TR> 184: <TR> 1.154.2.4 schwarze 185: <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD> 1.150 kristaps 186: <TD VALIGN="top"> 1.154.2.4 schwarze 187: man language reference 1.150 kristaps 188: </TD> 189: </TR> 190: <TR> 1.154.2.4 schwarze 191: <TD VALIGN="top"><A HREF="man.cgi.7.html">man.cgi(7)</A></TD> 1.112 kristaps 192: <TD VALIGN="top"> 1.154.2.4 schwarze 193: cgi for manpage query and display 1.112 kristaps 194: </TD> 195: </TR> 196: <TR> 197: <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD> 198: <TD VALIGN="top"> 199: mandoc special characters 200: </TD> 201: </TR> 202: <TR> 203: <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD> 204: <TD VALIGN="top"> 205: mdoc language reference 206: </TD> 207: </TR> 208: <TR> 209: <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD> 210: <TD VALIGN="top"> 211: roff-mandoc language reference 212: </TD> 213: </TR> 214: <TR> 215: <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD> 216: <TD VALIGN="top"> 217: tbl-mandoc language reference 218: </TD> 219: </TR> 1.138 kristaps 220: <TR> 1.150 kristaps 221: <TD VALIGN="top"><A HREF="catman.8.html">catman(8)</A></TD> 222: <TD VALIGN="top"> 223: update a man.cgi manpage cache 224: </TD> 225: </TR> 226: <TR> 1.138 kristaps 227: <TD VALIGN="top"><A HREF="mandocdb.8.html">mandocdb(8)</A></TD> 228: <TD VALIGN="top"> 229: index UNIX manuals 230: </TD> 231: </TR> 1.112 kristaps 232: </TBODY> 233: </TABLE> 1.154.2.10! schwarze 234: <H2> ! 235: <A NAME="links">Supplementary Information</A> ! 236: </H2> ! 237: <UL> ! 238: <LI> ! 239: <A HREF="http://manpages.bsd.lv/">Practical UNIX Manuals</A>: mdoc tutorial by Kristaps Dzonsons ! 240: </LI> ! 241: <LI> ! 242: <A HREF="http://www.openbsd.org/faq/ports/specialtopics.html#Mandoc" CLASS="external">OpenBSD porting guide</A> ! 243: chapter regarding manual pages ! 244: </LI> ! 245: <LI> ! 246: <A HREF="press.html">Publications and media coverage</A> ! 247: concerning mdocml and mandoc ! 248: </LI> ! 249: <LI> ! 250: <A HREF="http://manpages.bsd.lv/history.html">History of UNIX Manpages</A>: a comprehensive overview by Kristaps Dzonsons ! 251: </LI> ! 252: </UL> 1.112 kristaps 253: <H1> 1.118 kristaps 254: <A NAME="contact">Contact</A> 1.112 kristaps 255: </H1> 256: <P> 1.139 kristaps 257: Use the mailing lists for bug-reports, patches, questions, etc. Please check the 1.112 kristaps 258: <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues 1.139 kristaps 259: before posting. All lists are subscription-only: send a blank e-mail to the listed address to subscribe. Beyond that, 260: contact Kristaps at <A HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal 1.149 kristaps 261: this e-mail address">kris...</A>@bsd.lv. Archives are available at <A HREF="http://gmane.org/" CLASS="external">Gmane</A>. 1.112 kristaps 262: </P> 263: <TABLE WIDTH="100%" SUMMARY="Mailing Lists"> 1.136 kristaps 264: <COL WIDTH="175"> 1.112 kristaps 265: <COL> 266: <TBODY> 267: <TR> 268: <TD> 269: disc<A CLASS="external" TITLE="Reveal this e-mail address" 270: HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv 271: </TD> 272: <TD> 273: bug-reports, general questions, and announcements 274: </TD> 275: </TR> 276: <TR> 277: <TD> 278: tec<A CLASS="external" TITLE="Reveal this e-mail address" 279: HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv 280: </TD> 281: <TD> 282: patches and system discussions 283: </TD> 284: </TR> 285: <TR> 286: <TD> 287: sou<A CLASS="external" TITLE="Reveal this e-mail address" 288: HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv 289: </TD> 290: <TD> 291: source commit messages 292: </TD> 293: </TR> 294: </TBODY> 295: </TABLE> 296: <H1> 1.118 kristaps 297: <A NAME="news">News</A> 1.112 kristaps 298: </H1> 1.124 kristaps 299: <P CLASS="news"> 1.154.2.9 schwarze 300: 05-10-2013: version 1.12.2 1.154.2.3 schwarze 301: </P> 302: <P> 1.154.2.4 schwarze 303: The <A HREF="mdoc.7.html">mdoc(7)</A> to <A HREF="man.7.html">man(7)</A> converter, 304: to be called as <CODE>mandoc -Tman</CODE>, is now fully functional. 1.154.2.3 schwarze 305: </P> 306: <P> 307: The <A HREF="mandoc.1.html">mandoc(1)</A> utility now supports the <CODE>-Ios</CODE> (default operating system) 308: input option, and the <CODE>-Tutf8</CODE> output mode now actually works. 309: </P> 310: <P> 1.154.2.4 schwarze 311: The <A HREF="mandocdb.8.html">mandocdb(8)</A> utility no longer truncates existing databases when starting to build new ones, 312: but only replaces them when the build actually succeeds. 1.154.2.3 schwarze 313: </P> 314: <P> 315: The <A HREF="man.7.html">man(7)</A> parser now supports the <EM>PD</EM> macro (paragraph distance), 316: and (for GNU man-ext compatibility only) <EM>EX</EM> (example block) and <EM>EE</EM> (example end). 317: Plus several bugfixes regarding indentation, line breaks, and vertical spacing, 318: and regarding <EM>RS</EM> following <EM>TP</EM>. 319: </P> 320: <P> 321: The <A HREF="roff.7.html">roff(7)</A> parser now supports the <EM>\f(BI</EM> (bold+italic) font escape, 322: the <EM>\z</EM> (zero cursor advance) escape and the <EM>cc</EM> (change control character) 323: and <EM>it</EM> (input line trap) requests. 1.154.2.4 schwarze 324: Plus bugfixes regarding the <EM>\t</EM> (tab) escape, nested escape sequences, and conditional requests. 1.154.2.3 schwarze 325: </P> 326: <P> 1.154.2.4 schwarze 327: In <A HREF="mdoc.7.html">mdoc(7)</A>, several bugs were fixed related to UTF-8 output of quoting enclosures, 1.154.2.3 schwarze 328: delimiter handling, list indentation and horizontal and vertical spacing, 1.154.2.4 schwarze 329: formatting of the <EM>Lk</EM>, <EM>%U</EM>, and <EM>%C</EM> macros, 1.154.2.3 schwarze 330: plus some bugfixes related to the handling of syntax errors like badly nested font blocks, 331: stray <EM>Ta</EM> macros outside column lists, unterminated <EM>It Xo</EM> blocks, 332: and non-text children of <EM>Nm</EM> blocks. 333: </P> 334: <P> 1.154.2.4 schwarze 335: In <A HREF="tbl.7.html">tbl(7)</A>, the width of horizontal spans and the vertical spacing around tables was corrected, 336: and in <A HREF="man.7.html">man(7)</A> files, a crash was fixed that was triggered by some particular unclosed <EM>T{</EM> macros. 1.154.2.3 schwarze 337: </P> 338: <P> 339: For mandoc developers, we now provide a <A HREF="tbl.3.html">tbl(3)</A> library manual and <CODE>gmdiff</CODE>, 1.154.2.4 schwarze 340: a very small, very simplistic groff-versus-mandoc output comparison tool. 1.154.2.3 schwarze 341: </P> 1.154.2.7 schwarze 342: <P> 343: See <A HREF="NEWS">NEWS</A> for historical notes. 344: </P> 1.154.2.3 schwarze 345: <P CLASS="news"> 1.154.2.8 schwarze 346: 23-03-2012: version 1.12.1 1.149 kristaps 347: </P> 348: <P> 349: Significant work on <A HREF="apropos.1.html">apropos</A> and <A HREF="mandocdb.8.html">mandocdb</A>. These tools are 1.152 kristaps 350: now much more robust. 351: A <A HREF="whatis.1.html">whatis</A> implementation is now handled as an <A HREF="apropos.1.html">apropos</A> mode. 352: These tools are also able to minimally handle pre-formatted pages, that is, those already formatted by another utility 353: such as GNU troff. 1.150 kristaps 354: </P> 355: <P> 356: The <A HREF="man.cgi.7.html">man.cgi</A> script is also now available for wider testing. It interfaces with <A 357: HREF="mandocdb.8.html">mandocdb</A> manuals cached by <A HREF="catman.8.html">catman</A>. HTML output is generated 358: on-the-fly by <A HREF="mandoc.3.html">libmandoc</A> or internal methods to convert pre-formatted pages. 1.149 kristaps 359: </P> 1.151 kristaps 360: <P> 1.152 kristaps 361: The mailing list archive for the discuss and tech lists are being hosted by <A CLASS="external" 1.151 kristaps 362: HREF="http://www.gmane.org">Gmane</A> at <A HREF="http://dir.gmane.org/gmane.comp.tools.mdocml.user" 363: CLASS="external">gmane.comp.tools.mdocml.user</A> and <A HREF="http://dir.gmane.org/gmane.comp.tools.mdocml.devel" 364: CLASS="external">gmane.comp.tools.mdocml.devel</A>, respectively. 365: </P> 1.142 kristaps 366: <P> 1.152 kristaps 367: Lastly, I'm no longer providing binaries, as nobody has asked for them. 1.112 kristaps 368: </P> 369: <P CLASS="foot"> 1.118 kristaps 370: <SMALL> 371: Copyright © 2008–2011 372: <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>, 1.154.2.4 schwarze 373: © 2013 Ingo Schwarze, 1.154.2.9 schwarze 374: $Date: 2013/10/05 16:11:00 $ 1.118 kristaps 375: </SMALL> 1.112 kristaps 376: </P> 1.40 kristaps 377: </BODY> 378: </HTML>