path: root/index.sgml



<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta name="resource-type" content="document">
		<link rel="stylesheet" href="style.css" type="text/css" media="all">
		<title>mdocml.bsd.lv</title>
	</head>
	<body>
	<table width="600">
		<col width="100%">
		<tbody>
			<tr>
				<td>
					<div class="head">
						<b>mdocml</b> &#8211; mdoc macro compiler
					</div>
				</td>
			</tr>
			<tr>
				<td valign="top">
					<h1>
					DESCRIPTION
					</h1>

					<p>
					<span class="nm">mdocml</span> is a suite of tools compiling &#8220;-mdoc&#8221;, the roff macro package
					of choice for BSD manual pages, and &#8220;-man&#8221;, the predominant historical package for UNIX
					manuals.  The mission of <span class="nm">mdocml</span> is to deprecate <a
					href="http://www.gnu.org/software/groff/" class="external">groff</a>, the GNU roff implementation, for
					displaying -mdoc pages whilst providing token support for -man.
					</p>

					<p>
					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 uncertain output, and varies in operation from system to system.  mdocml strives to fix
					this (respectively small, C, ISC-licensed, fast and regular).
					</p>

					<p>
					The core of <span class="nm">mdocml</span> is composed of the <i>libmdoc</i> and <i>libman</i>
					validating compiler libraries.  Both are simple, fast libraries operating on memory buffers, so they may
					be used for a variety of front-ends (terminal-based, CGI and so on).  The primary front-end is <i>
					mandoc</i>, which formats manuals for display on the terminal.
					</p>
				</td>
			</tr>
			<tr>
				<td>
					<h1>
					INSTALLING SOURCES
					</h1>

					<p>
					Sources correctly build and install on FreeBSD, OpenBSD, NetBSD and Linux operating systems, tested
					variously on i386, AMD64, alpha and others.  The most current version is <span
					class="attn">@VERSION@</span>, dated <span class="attn">@VDATE@</span>.  
					</p>

					<h2>
					Snapshot source
					</h2>

					<p>
					CVS sources are checkedout and snapshotted with version updates.  These (and all historical snapshots)
					may be found in the <a href="/snapshots/">/snapshots/</a> directory.  A full <a
					href="/snapshots/ChangeLog">ChangeLog</a> is written with each new snapshot.
					</p>

					<p class="boxed">
					% cd /tmp<br>
					% ftp -V -o- <a href="http://mdocml.bsd.lv/snapshots/mdocml.tar.gz">
					http://mdocml.bsd.lv/snapshots/mdocml.tar.gz</a> | tar -zvxf -<br>
					% cd mdocml<br>
					% make all<br>
					# make install
					</p>

					<h2>
					Snapshot port/pkgsrc
					</h2>

					<p>
					The source snapshot is automatically converted into OpenBSD, NetBSD and FreeBSD ports at <a
					href="/ports-openbsd/">/ports-openbsd/</a>, <a href="/ports-netbsd/">/ports-netbsd/</a> and <a
					href="/ports-freebsd/">/ports-freebsd/</a>, respectively.  Please read the <a class="external"
					href="http://www.openbsd.org/faq/faq15.html">OpenBSD Ports FAQ</a>, the <a class="external"
					href="http://www.netbsd.org/docs/software/packages.html">NetBSD pkgsrc guide</a> or the <a
					class="external"
					href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports-using.html">FreeBSD ports
					guide</a>, first.
					</p>

					<h3>
					OpenBSD port
					</h3>

					<p>
					Note: the <span class="nm">mdocml</span> utility is part of OpenBSD's base system at <a
					href="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/">usr.bin/mandoc</a>.  Please use this
					instead of the provided port.
					</p>

					<p class="boxed">
					# pkg_delete mdocml<br>
					# cd /usr/ports/textproc/<br>
					# rm -rf mdocml<br>
					# ftp -V -o- <a href="http://mdocml.bsd.lv/ports-openbsd/mdocml.tar.gz">
					http://mdocml.bsd.lv/ports-openbsd/mdocml.tar.gz</a> | tar -zvxf -<br>
					# cd mdocml<br>
					# make build<br>
					# make install
					</p>

					<h3>
					NetBSD pkgsrc
					</h3>

					<p>
					Note: a pkgsrc port is maintained in-tree at <a
					href="http://cvsweb.netbsd.org/bsdweb.cgi/pkgsrc/textproc/mdocml/">textproc/mdocml</a>.  Please use this
					instead of the provided pkgsrc.
					</p>

					<p class="boxed">
					# pkg_delete mdocml<br>
					# cd /usr/pkgsrc/textproc/<br>
					# rm -rf mdocml<br>
					# ftp -V -o- <a href="http://mdocml.bsd.lv/ports-netbsd/mdocml.tar.gz">
					http://mdocml.bsd.lv/ports-netbsd/mdocml.tar.gz</a> | tar -zvxf -<br>
					# cd mdocml<br>
					# make build<br>
					# make install
					</p>

					<h3>
					FreeBSD port
					</h3>

					<p>
					Note: a port is maintained in-tree at <a
					href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/">textproc/mdocml</a>.  Please use
					this instead of the provided port.
					</p>

					<p class="boxed">
					# pkg_delete -x mdocml<br>
					# cd /tmp<br>
					# ftp -V -o- <a href="http://mdocml.bsd.lv/ports-freebsd/mdocml.tar.gz">
					http://mdocml.bsd.lv/ports-freebsd/mdocml.tar.gz</a> | tar -zvxf -<br>
					# cd mdocml<br>
					# make<br>
					# make install
					</p>
				</td>
			</tr>
			<tr>
				<td>
					<h1>
					DOCUMENTATION
					</h1>

					<table width="100%">
						<colgroup>
							<col>
							<col width="5">
							<col width="100%">
						</colgroup>
						<tr>
							<td><a href="mandoc.1.txt">mandoc(1)</a></td>
							<td></td>
							<td>format and display UNIX manuals</td>
						</tr>
						<tr>
							<td><a href="mandoc_char.7.txt">mandoc_char(7)</a></td>
							<td></td>
							<td>mandoc special characters</td>
						</tr>
						<tr>
							<td><a href="mdoc.7.txt">mdoc(7)</a></td>
							<td></td>
							<td>mdoc language reference</td>
						</tr>
						<tr>
							<td><a href="man.7.txt">man(7)</a></td>
							<td></td>
							<td>man language reference</td>
						</tr>
						<tr>
							<td><a href="manuals.7.txt">manuals(7)</a></td>
							<td></td>
							<td>a guide to writing UNIX manuals</td>
						</tr>
						<tr>
							<td><a href="mdoc.3.txt">mdoc(3)</a></td>
							<td></td>
							<td>mdoc macro compiler library</td>
						</tr>
						<tr>
							<td><a href="man.3.txt">man(3)</a></td>
							<td></td>
							<td>man macro compiler library</td>
						</tr>
					</table>
				</td>
			</tr>
			<tr>
				<td>
					<h1>
					CONTACT
					</h1>

					<p>
					For all issues related to <span class="nm">mdocml</span>, contact Kristaps, kris<a class="external"
					href="http://mailhide.recaptcha.net/d?k=01jt88xIsFONwVjHZmGpc4AQ==&amp;c=sb5E6ulipc-eTnpTVqI-BQ=="
					onclick="window.open('http://mailhide.recaptcha.net/d?k=01jt88xIsFONwVjHZmGpc4AQ==&amp;c=sb5E6ulipc-eTnpTVqI-BQ==',
					'', 'toolbar=0,scrollbars=0,location=0,statusbar=0,menubar=0,resizable=0,width=500,height=300'); return
					false;" title="Reveal this e-mail address">...</a>@kth.se.
					</p>

					<p>
					If you want to receive a semi-automated mail-out of new versions, then please write with a message
					subject of &#8220;subscribe mdocml&#8221; (or, symmetrically, &#8220;unsubscribe mdocml&#8221;).
					</p>

					<p>
					We don't offer anonymous CVS access.  If you must have read-only access to the CVS tree (for down-stream
					maintenance and so on), then please contact Kristaps directly for a read-only CVS account.  We strongly
					suggest using snapshots, instead.
					</p>
				</td>
			</tr>
			<tr>
				<td>
					<div class="foot">
						Copyright &#169; 2008, 2009 Kristaps D&#382;onsons, $Date$
					</div>
				</td>
			</tr>
		</tbody>
	</table>
	</body>
</html>