mandoc/index.sgml - diff

Return to index.sgml CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/Attic/index.sgml between version 1.115 and 1.160

version 1.115, 2011/05/13 00:42:26

version 1.160, 2013/10/05 20:09:24

Line 3

<HEAD>

<TITLE>mdocml | mdoc macro compiler</TITLE>

<TITLE>mdocml | UNIX manpage compiler</TITLE>

</HEAD>

<BODY>

<B>mdocml</B> – mdoc macro compiler

<B>mdocml</B> – UNIX manpage compiler, current version @VERSION@ (@VDATE@)

</P>

Sources: <A HREF="/snapshots/mdocml.tar.gz">current</A>,

<A HREF="/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>

(<A HREF="/snapshots/">archives</A>)

</P>

<H1>

<A NAME="description">DESCRIPTION</A>

<A NAME="description">Description</A>

</H1>

<P>

<SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <I><A HREF="mdoc.7.html">mdoc</A></I>, the roff macro

package of choice for BSD manual pages, and <I><A HREF="man.7.html">man</A></I>, the predominant historical package for

Line 21

Line 24

HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU troff implementation, for displaying <I>mdoc</I>

pages whilst providing token support for <I>man</I>.

</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

Why? groff amounts to over 5 MB of source code, most of which is C++ and GPL version 3. It runs slowly, produces

uncertain output, and varies in operation from system to system. mdocml strives to fix this (respectively small, C, <A

CLASS="external" HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).

</P>

<P>

<SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating compiler and <A

HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format output for UNIX terminals, XHTML,

HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format output for UNIX terminals (with

HTML, PostScript, and PDF. It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.

support for wide-character locales), XHTML, HTML, PostScript, and PDF.

It also includes <A HREF="preconv.1.html">preconv</A> for recoding multibyte manuals,

<A HREF="demandoc.1.html">demandoc</A> for emitting only text parts of manuals,

<A HREF="mandocdb.8.html">mandocdb</A> for indexing manuals,

<A HREF="apropos.1.html">apropos</A> (includes whatis mode) for indexed manual search, and

<A HREF="man.cgi.7.html">man.cgi</A> for indexed manual search online.

It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.

</P>

<P>

<I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary, <Q>mandoc</Q>.

</P>

<H2>

<H1>

<A NAME="sources">Sources</A>

<A NAME="sources">SOURCES</A>

</H2>

</H1>

<P>

<SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any UNIX system. The most current

<SPAN CLASS="nm">mdocml</SPAN> is in ISO C99 and should build and run on any modern system; however, you'll need <A

version is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>. If your system doesn't come

HREF="http://www.sqlite.org">sqlite3</A> to build <A HREF="apropos.1.html">apropos</A> (links to whatis),

with <SPAN CLASS="nm">mdocml</SPAN> (see <Q>Downstream</Q>), run <CODE>make</CODE> to compile and <CODE>make

<A HREF="man.cgi.7.html">man.cgi</A>, and <A HREF="mandocdb.8.html">mandocdb</A>.

install</CODE> to install into <I>/usr/local</I>.

To build and install into <I>/usr/local/</I>, just run <CODE>make install</CODE>.

Be careful: the <B>preconv</B>, <B>apropos</B>, and <B>whatis</B> binary names are usually taken by existing utilities.

</P>

<P>

Note that <A HREF="makewhatis.1.html">makewhatis</A> is not yet linked to the build. You must run <CODE>make

makewhatis</CODE> to build it.

</P>

<H2>

Current

Downstream

</H2>

<P>

Several systems come bundled with <SPAN CLASS="nm">mdocml</SPAN> utilities.

If your system does not appear below, the maintainers have not contacted me and it should not be considered

<Q>official</Q>.

Please <A HREF="#contact">contact us</A> if you plan on maintaining a downstream version!

</P>

<COL>

<TBODY>

<TR>

<TD>Source archive</TD>

<TD>DragonFly BSD</TD>

<TD>

<A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>

<A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/contrib/mdocml" CLASS="external">contrib/mdocml</A> (1.12.1 sources)

(<A HREF="/snapshots/mdocml.md5">md5</A>)

<A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/lib/libmandoc" CLASS="external">lib/libmandoc</A>

<A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc" CLASS="external">usr.bin/mandoc</A> (build system)

</TD>

</TR>

<TR>

<TD>Online source</TD>

<TD>FreeBSD 10.0, -CURRENT</TD>

<TD>

<A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>

<A HREF="http://svnweb.freebsd.org/base/head/contrib/mdocml/" CLASS="external">contrib/mdocml</A> (1.12.1 sources)

<A HREF="http://svnweb.freebsd.org/base/head/usr.bin/mandoc/" CLASS="external">usr.bin/mandoc</A> (build system)

</TD>

</TR>

</TBODY>

</TABLE>

<H2>

Downstream

</H2>

<COL>

<TBODY>

<TR>

<TD>DragonFly BSD</TD>

<TD>FreeBSD 9.x, 8.x</TD>

<TD>

<A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"

<A HREF="http://svnweb.freebsd.org/ports/head/textproc/mdocml/" CLASS="external">ports/textproc/mdocml</A> (1.12.1 port)

CLASS="external">usr.bin/mandoc</A>

</TD>

</TR>

<TR>

<TD>FreeBSD</TD>

<TD>NetBSD</TD>

<TD>

<A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"

<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)

CLASS="external">ports/textproc/mdocml</A>

</TD>

</TR>

<TR>

<TD>NetBSD</TD>

<TD>OpenBSD</TD>

<TD>

<A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"

<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)

CLASS="external">src/external/bsd/mdocml</A>

</TD>

</TR>

<TR>

<TD>OpenBSD</TD>

<TD>pkgsrc</TD>

<TD>

<A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"

<A HREF="http://pkgsrc.se/textproc/mdocml" CLASS="external">textproc/mdocml</A> (1.12.2 port)

CLASS="external">src/usr.bin/mandoc</A>

</TD>

</TR>

</TBODY>

</TABLE>

<H2>

Historical

</H2>

<COL>

<TBODY>

<TR>

<TD>Source archive</TD>

<TD>Minix3</TD>

<TD>

<A HREF="/snapshots/">/snapshots/</A>

<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)

</TD>

</TR>

<TR>

<TD>Alpine Linux</TD>

<TD>

<A HREF="http://git.alpinelinux.org/cgit/aports/tree/main/mdocml" CLASS="external">aports/main/mdocml</A> (1.12.1 port)

</TD>

</TR>

</TBODY>

</TABLE>

<H1>

<A NAME="documentation">DOCUMENTATION</A>

<A NAME="documentation">Documentation</A>

</H1>

<P>

These manuals are generated automatically and refer to the current snapshot.

These manuals are generated automatically and refer to the current release.

They are the authoritative documentation for the <SPAN CLASS="nm">mdocml</SPAN> system.

</P>

Line 146

Line 132

<COL>

<TBODY>

<TR>

<TD VALIGN="top"><A HREF="apropos.1.html">apropos(1)</A></TD>

search the manual page database

</TD>

</TR>

<TR>

<TD VALIGN="top"><A HREF="demandoc.1.html">demandoc(1)</A></TD>

emit only text of UNIX manuals

</TD>

</TR>

<TR>

<TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>

format and display UNIX manuals

<SMALL>

(<A HREF="mandoc.1.txt">text</A> |

<A HREF="mandoc.1.xhtml">xhtml</A> |

<A HREF="mandoc.1.pdf">pdf</A> |

<A HREF="mandoc.1.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

<TD VALIGN="top"><A HREF="mandoc.1.html">makewhatis(1)</A></TD>

<TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD>

index UNIX manuals

recode multibyte UNIX manuals

<SMALL>

(<A HREF="makewhatis.1.txt">text</A> |

<A HREF="makewhatis.1.xhtml">xhtml</A> |

<A HREF="makewhatis.1.pdf">pdf</A> |

<A HREF="makewhatis.1.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

<TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>

mandoc macro compiler library

<SMALL>

(<A HREF="mandoc.3.txt">text</A> |

<A HREF="mandoc.3.xhtml">xhtml</A> |

<A HREF="mandoc.3.pdf">pdf</A> |

<A HREF="mandoc.3.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

man language reference

roff table parser library for mandoc

<SMALL>

(<A HREF="man.7.txt">text</A> |

<A HREF="man.7.xhtml">xhtml</A> |

<A HREF="man.7.pdf">pdf</A> |

<A HREF="man.7.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

eqn-mandoc language reference

<SMALL>

(<A HREF="eqn.7.txt">text</A> |

<A HREF="eqn.7.xhtml">xhtml</A> |

<A HREF="eqn.7.pdf">pdf</A> |

<A HREF="eqn.7.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

man language reference

</TD>

</TR>

<TR>

cgi for manpage query and display

</TD>

</TR>

<TR>

<TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>

mandoc special characters

<SMALL>

(<A HREF="mandoc_char.7.txt">text</A> |

<A HREF="mandoc_char.7.xhtml">xhtml</A> |

<A HREF="mandoc_char.7.pdf">pdf</A> |

<A HREF="mandoc_char.7.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

mdoc language reference

<SMALL>

(<A HREF="mdoc.7.txt">text</A> |

<A HREF="mdoc.7.xhtml">xhtml</A> |

<A HREF="mdoc.7.pdf">pdf</A> |

<A HREF="mdoc.7.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

roff-mandoc language reference

<SMALL>

(<A HREF="roff.7.txt">text</A> |

<A HREF="roff.7.xhtml">xhtml</A> |

<A HREF="roff.7.pdf">pdf</A> |

<A HREF="roff.7.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

tbl-mandoc language reference

<SMALL>

(<A HREF="tbl.7.txt">text</A> |

<A HREF="tbl.7.xhtml">xhtml</A> |

<A HREF="tbl.7.pdf">pdf</A> |

<A HREF="tbl.7.ps">postscript</A>)

</SMALL>

</TD>

</TR>

<TR>

<TD VALIGN="top"><A HREF="mandocdb.8.html">mandocdb(8)</A></TD>

index UNIX manuals

</TD>

</TR>

</TBODY>

</TABLE>

<H1>

<A NAME="contact">CONTACT</A>

<A NAME="contact">Contact</A>

</H1>

<P>

Use the mailing lists for bug-reports, patches, questions, etc. (these require subscription). Please check the

Use the mailing lists for bug-reports, patches, questions, etc. Please check the

<A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues

before posting. Beyond that, contact Kristaps at <A

before posting. All lists are subscription-only: send a blank e-mail to the listed address to subscribe. Beyond that,

HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal

contact Kristaps at <A HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal

this e-mail address">kris...</A>@bsd.lv.

this e-mail address">kris...</A>@bsd.lv. Archives are available at <A HREF="http://gmane.org/" CLASS="external">Gmane</A>.

</P>

<COL>

Line 279

Line 238

</TD>

<TD>

bug-reports, general questions, and announcements

<SMALL>(<A HREF="/archives/discuss/summary.html">archive</A>)</SMALL>

</TD>

</TR>

<TR>

Line 289

Line 247

</TD>

<TD>

patches and system discussions

<SMALL>(<A HREF="/archives/tech/summary.html">archive</A>)</SMALL>

</TD>

</TR>

<TR>

Line 299

Line 256

</TD>

<TD>

source commit messages

<SMALL>(<A HREF="/archives/source/summary.html">archive</A>)</SMALL>

</TD>

</TR>

</TBODY>

</TABLE>

<H1>

</H1>

12-05-2011: version 1.11.2

xx-xx-2013: version 1.13.0

</P>

<P>

Corrected some installation issues in version 1.11.1.

The <A HREF="mandocdb.8.html">mandocdb</A> tools (<A HREF="mandocdb.8.html">mandocdb</A>, <A

Initial public release (this utility is very much under development) of <A HREF="makewhatis.1.html">makewhatis</A>,

HREF="apropos.1.html">apropos</A> (absorbing whatis), and <A HREF="man.cgi.7.html">man.cgi</A>) have been re-written to

initially named mandoc-db.

use <A CLASS="external" HREF="http://www.sqlite.org">sqlite3</A> as a database.

This utility produces keyword databases of manual content

<A HREF="http://mdocml.bsd.lv/mandoc-cgi/index.html">mandoc-cgi</A>, which features semantic querying of manual content.

</P>

04-04-2011: version 1.11.1

05-10-2013: version 1.12.2

</P>

<P>

The earlier <I>libroff</I>, <I>libmdoc</I>, and <I>libman</I> soup have been merged into

The <A HREF="mdoc.7.html">mdoc(7)</A> to <A HREF="man.7.html">man(7)</A> converter,

a single library, <A HREF="mandoc.3.html">libmandoc</A>, which manages all aspects of

to be called as <CODE>mandoc -Tman</CODE>, is now fully functional.

parsing real manuals (from line-handling to <A HREF="tbl.7.html">tbl</A> parsing).

</P>

<P>

Beyond this structural change, initial <A HREF="eqn.7.html">eqn</A> functionality is in

The <A HREF="mandoc.1.html">mandoc(1)</A> utility now supports the <CODE>-Ios</CODE> (default operating system)

place. For the time being, this is limited to the recognition of equation blocks;

input option, and the <CODE>-Tutf8</CODE> output mode now actually works.

future version of <SPAN CLASS="nm">mdocml</SPAN> will expand upon this framework.

</P>

<P>

As usual, many general fixes and improvements have also occurred. In particular, a great

The <A HREF="mandocdb.8.html">mandocdb(8)</A> utility no longer truncates existing databases when starting to build new ones,

deal of redundancy and superfluous code has been removed with the merging of the backend

but only replaces them when the build actually succeeds.

libraries.

</P>

<P>

The <A HREF="man.7.html">man(7)</A> parser now supports the <EM>PD</EM> macro (paragraph distance),

07-01-2011: version 1.10.9

and (for GNU man-ext compatibility only) <EM>EX</EM> (example block) and <EM>EE</EM> (example end).

Plus several bugfixes regarding indentation, line breaks, and vertical spacing,

and regarding <EM>RS</EM> following <EM>TP</EM>.

</P>

<P>

Many back-end fixes have been implemented: argument handling (quoting), <A

The <A HREF="roff.7.html">roff(7)</A> parser now supports the <EM>\f(BI</EM> (bold+italic) font escape,

HREF="man.7.html">man</A> improvements, error/warning classes, and many more.

the <EM>\z</EM> (zero cursor advance) escape and the <EM>cc</EM> (change control character)

and <EM>it</EM> (input line trap) requests.

Plus bugfixes regarding the <EM>\t</EM> (tab) escape, nested escape sequences, and conditional requests.

</P>

<P>

Initial <A HREF="tbl.7.html">tbl</A> functionality (see the <Q>TS</Q>, <Q>TE</Q>, and

In <A HREF="mdoc.7.html">mdoc(7)</A>, several bugs were fixed related to UTF-8 output of quoting enclosures,

<Q>T&</Q> macros in the <A HREF="roff.7.html#x5c265453">roff</A> manual) has been

delimiter handling, list indentation and horizontal and vertical spacing,

merged from <A CLASS="external" HREF="http://tbl.bsd.lv">tbl.bsd.lv</A>. Output is

formatting of the <EM>Lk</EM>, <EM>%U</EM>, and <EM>%C</EM> macros,

still minimal, especially for <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN

plus some bugfixes related to the handling of syntax errors like badly nested font blocks,

CLASS="flag">-Txhtml</SPAN>, but manages to at least display data. This means that <A

stray <EM>Ta</EM> macros outside column lists, unterminated <EM>It Xo</EM> blocks,

HREF="mandoc.1.html">mandoc</A> now has built-in support for two troff preprocessors via

and non-text children of <EM>Nm</EM> blocks.

<DEL>libroff</DEL>: soelim and tbl.

</P>

<P>

In <A HREF="tbl.7.html">tbl(7)</A>, the width of horizontal spans and the vertical spacing around tables was corrected,

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.

</P>

<P>

For mandoc developers, we now provide a <A HREF="tbl.3.html">tbl(3)</A> library manual and <CODE>gmdiff</CODE>,

a very small, very simplistic groff-versus-mandoc output comparison tool.

</P>

<P>

See <A HREF="NEWS">NEWS</A> for historical notes.

</P>

24-12-2010: version 1.10.8

23-03-2012: version 1.12.1

</P>

<P>

Significant improvements merged from <A CLASS="external"

Significant work on <A HREF="apropos.1.html">apropos</A> and <A HREF="mandocdb.8.html">mandocdb</A>. These tools are

HREF="http://www.openbsd.org">OpenBSD</A> downstream, including

now much more robust.

A <A HREF="whatis.1.html">whatis</A> implementation is now handled as an <A HREF="apropos.1.html">apropos</A> mode.

These tools are also able to minimally handle pre-formatted pages, that is, those already formatted by another utility

such as GNU troff.

</P>

<UL>

<LI>many new <A HREF="roff.7.html">roff</A> components,</LI>

<LI>in-line implementation of troff's soelim,</LI>

<LI>broken-block handling,</LI>

<LI>overhauled error classifications, and</LI>

<LI>cleaned up handling of error conditions.</LI>

</UL>

<P>

Also overhauled the <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN

The <A HREF="man.cgi.7.html">man.cgi</A> script is also now available for wider testing. It interfaces with <A

CLASS="flag">-Txhtml</SPAN> output modes. They now display readable output in arbitrary

HREF="mandocdb.8.html">mandocdb</A> manuals cached by <A HREF="catman.8.html">catman</A>. HTML output is generated

browsers, including text-based ones like <A CLASS="external"

on-the-fly by <A HREF="mandoc.3.html">libmandoc</A> or internal methods to convert pre-formatted pages.

HREF="http://lynx.isc.org">lynx</A>. See HTML and XHTML manuals in the <A

HREF="#documentation">DOCUMENTATION</A> section for examples. <SPAN

CLASS="attn">Attention: available style-sheet classes have been considerably

changed!</SPAN> See the <SPAN CLASS="file">example.style.css</SPAN> file for details.

Lastly, <DEL>libmdoc</DEL> and <DEL>libman</DEL> have been

cleaned up and reduced in size and complexity.

</P>

<P>

The mailing list archive for the discuss and tech lists are being hosted by <A CLASS="external"

HREF="http://www.gmane.org">Gmane</A> at <A HREF="http://dir.gmane.org/gmane.comp.tools.mdocml.user"

CLASS="external">gmane.comp.tools.mdocml.user</A> and <A HREF="http://dir.gmane.org/gmane.comp.tools.mdocml.devel"

CLASS="external">gmane.comp.tools.mdocml.devel</A>, respectively.

</P>

<P>

Lastly, I'm no longer providing binaries, as nobody has asked for them.

</P>

<P>

See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for

historical notes.

</P>

<SMALL>

<A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,

$Date$

<A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,

$Date$

</SMALL>

</P>

</BODY>

</HTML>

CVSweb