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.114 and 1.154.2.3

version 1.114, 2011/05/04 08:21:17

version 1.154.2.3, 2013/09/18 19:07:37

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

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; and

<A HREF="apropos.1.html">apropos</A>, <A HREF="whatis.1.html">whatis</A>, and

<A HREF="man.cgi.7.html">man.cgi</A> (via <A HREF="catman.8.html">catman</A>) for semantic search of manual content.

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 plain-old ANSI C and should build and run on any modern system; however, you'll

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

need <A HREF="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">libdb</A> to build <A

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

HREF="apropos.1.html">apropos</A>, <A HREF="whatis.1.html">whatis</A>, <A HREF="man.cgi.7.html">man.cgi</A>, <A

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

HREF="catman.8.html">catman</A>, and <A HREF="mandocdb.8.html">mandocdb</A> (this is installed by default on BSD UNIX

systems — see the <I>Makefile</I> if you're running Linux). 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="mandoc-db.1.html">mandoc-db</A> is not yet linked to the build. You must run <CODE>make

mandoc-db</CODE> to build it.

</P>

<H2>

Current

</H2>

<COL>

<TBODY>

<TR>

<TD>Source archive</TD>

<TD>

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

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

</TD>

</TR>

<TR>

<TD>Online source</TD>

<TD>

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

</TD>

</TR>

</TBODY>

</TABLE>

<H2>

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>

Line 88

Line 71

<TR>

<TD>DragonFly BSD</TD>

<TD>

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

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

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

</TD>

</TR>

<TR>

<TD>FreeBSD</TD>

<TD>

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

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

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

</TD>

</TR>

<TR>

<TD>NetBSD</TD>

<TD>

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

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

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

</TD>

</TR>

<TR>

<TD>OpenBSD</TD>

<TD>

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

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

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

</TD>

</TR>

</TBODY>

</TABLE>

<H2>

Historical

</H2>

<COL>

<TBODY>

<TR>

<TD>Source archive</TD>

<TD>pkgsrc</TD>

<TD>

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

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

</TD>

</TR>

<TR>

<TD>Minix3</TD>

<TD>

<A HREF="http://git.minix3.org/?p=minix.git;a=tree;f=external/bsd/mdocml" CLASS="external">external/bsd/mdocml</A>

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

<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">mandoc-db(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="mandoc-db.1.txt">text</A> |

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

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

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

</SMALL>

</TD>

</TR>

<TR>

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

search the manual page database

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

roff table parser library for mandoc

</TD>

</TR>

<TR>

man language reference

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

cgi for manpage query and display

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

<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="catman.8.html">catman(8)</A></TD>

update a man.cgi manpage cache

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

</TD>

<TD>

bug-reports, general questions, and announcements

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

</TD>

</TR>

<TR>

Line 289

Line 246

</TD>

<TD>

patches and system discussions

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

</TD>

</TR>

<TR>

Line 299

Line 255

</TD>

<TD>

source commit messages

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

</TD>

</TR>

</TBODY>

</TABLE>

<H1>

</H1>

04-04-2011: version 1.11.1

18-09-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 main new feature in mandoc 1.12.2 is that the <A HREF="mdoc.7.html">mdoc(7)</A> to <A HREF="man.7.html">man(7)</A>

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

converter, 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

In <A HREF="mandocdb.8.html">mandocdb(8)</A>, do not truncate existing databases when starting to build new ones,

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

only replace 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, regarding nested escape sequences,

and regarding 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 bugfixes 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 fixes to <EM>Lk</EM>, <EM>%U</EM>, and <EM>%C</EM>,

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>, correct the width of horizontal spans, the vertical spacing around tables

in <A HREF="man.7.html">man(7)</A> files, and fix a crash caused 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 simplistic groff-versus-mandoc output comparison tool.

</P>

24-12-2010: version 1.10.8

23-03-2011: 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