[BACK]Return to index.sgml CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/index.sgml, Revision 1.64

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:                <META NAME="resource-type" CONTENT="document">
                      6:                <LINK REL="stylesheet" HREF="index.css" TYPE="text/css" MEDIA="all">
1.47      kristaps    7:                <TITLE>mdocml | mdoc macro compiler</TITLE>
1.40      kristaps    8:        </HEAD>
                      9:        <BODY>
                     10:        <TABLE CLASS="frame" SUMMARY="[frame]">
                     11:                <COL WIDTH="100%">
                     12:                <TBODY>
                     13:                        <TR>
                     14:                                <TD>
                     15:                                        <DIV CLASS="head">
                     16:                                                <B>mdocml</B> &#8211; mdoc macro compiler
                     17:                                        </DIV>
                     18:                                </TD>
                     19:                        </TR>
                     20:                        <TR>
                     21:                                <TD VALIGN="top">
                     22:                                        <H1>
1.1       kristaps   23:                                        DESCRIPTION
1.40      kristaps   24:                                        </H1>
1.1       kristaps   25:
1.40      kristaps   26:                                        <P>
                     27:                                        <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <Q>-mdoc</Q>, the roff macro package
                     28:                                        of choice for BSD manual pages, and <Q>-man</Q>, the predominant historical package for UNIX
                     29:                                        manuals.  The mission of <SPAN CLASS="nm">mdocml</SPAN> is to deprecate <A
                     30:                                        HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU roff implementation, for
1.18      kristaps   31:                                        displaying -mdoc pages whilst providing token support for -man.
1.40      kristaps   32:                                        </P>
1.9       kristaps   33:
1.40      kristaps   34:                                        <P>
1.13      kristaps   35:                                        Why?  groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL.  It runs
                     36:                                        slowly, produces uncertain output, and varies in operation from system to system.  mdocml strives to fix
                     37:                                        this (respectively small, C, ISC-licensed, fast and regular).
1.40      kristaps   38:                                        </P>
1.1       kristaps   39:
1.40      kristaps   40:                                        <P>
                     41:                                        The core of <SPAN CLASS="nm">mdocml</SPAN> is composed of the <i>libmdoc</i> and <i>libman</i>
1.19      kristaps   42:                                        validating compiler libraries.  Both are simple, fast libraries operating on memory buffers, so they may
                     43:                                        be used for a variety of front-ends (terminal-based, CGI and so on).  The primary front-end is <i>
                     44:                                        mandoc</i>, which formats manuals for display on the terminal.
1.40      kristaps   45:                                        </P>
                     46:
                     47:                                        <P>
                     48:                                        The <SPAN CLASS="nm">mdocml</SPAN> utility is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv
                     49:                                        Project</A> member.
                     50:                                        </P>
                     51:                                </TD>
                     52:                        </TR>
                     53:                        <TR>
                     54:                                <TD>
                     55:                                        <H1>
1.33      kristaps   56:                                        SOURCES
1.40      kristaps   57:                                        </H1>
1.1       kristaps   58:
1.40      kristaps   59:                                        <P>
1.39      kristaps   60:                                        Sources correctly build and install on DragonFly BSD, FreeBSD, OpenBSD, NetBSD, and GNU/Linux operating
1.40      kristaps   61:                                        systems, tested variously on i386, AMD64, alpha, and others.  The most current version is <SPAN
                     62:                                        CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>.  A full <A
                     63:                                        HREF="ChangeLog.html">ChangeLog</A> (<A HREF="ChangeLog.txt">txt</A>) is written with each release.
                     64:                                        </P>
1.7       kristaps   65:
1.40      kristaps   66:                                        <H2>
1.26      kristaps   67:                                        Current
1.40      kristaps   68:                                        </H2>
1.1       kristaps   69:
1.40      kristaps   70:                                        <TABLE WIDTH="100%" SUMMARY="Current Sources">
                     71:                                        <COL WIDTH="200">
                     72:                                        <COL>
                     73:                                        <TBODY>
                     74:                                                <TR>
                     75:                                                        <TD>Source archive</TD>
                     76:                                                        <TD>
                     77:                                                        <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
                     78:                                                        (<A HREF="/snapshots/mdocml.md5">md5</A>)
                     79:                                                        </TD>
                     80:                                                </TR>
                     81:                                                <TR>
                     82:                                                        <TD>Online source</TD>
                     83:                                                        <TD>
                     84:                                                        <A CLASS="external" HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
                     85:                                                        </TD>
                     86:                                                </TR>
                     87:                                        </TBODY>
                     88:                                        </TABLE>
1.1       kristaps   89:
1.40      kristaps   90:                                        <H2>
1.26      kristaps   91:                                        Downstream
1.40      kristaps   92:                                        </H2>
1.1       kristaps   93:
1.40      kristaps   94:                                        <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
                     95:                                        <COL WIDTH="200">
                     96:                                        <COL>
                     97:                                        <TBODY>
                     98:                                                <TR>
                     99:                                                        <TD>DragonFly BSD</TD>
                    100:                                                        <TD>
                    101:                                                        <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
                    102:                                                                CLASS="external">usr.bin/mandoc</A>
                    103:                                                        </TD>
                    104:                                                </TR>
                    105:                                                <TR>
                    106:                                                        <TD>FreeBSD</TD>
                    107:                                                        <TD>
                    108:                                                        <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
                    109:                                                                CLASS="external">ports/textproc/mdocml</A>
                    110:                                                        </TD>
                    111:                                                </TR>
                    112:                                                <TR>
                    113:                                                        <TD>NetBSD</TD>
                    114:                                                        <TD>
                    115:                                                        <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
                    116:                                                                CLASS="external">src/external/bsd/mdocml</A>
                    117:                                                        </TD>
                    118:                                                </TR>
                    119:                                                <TR>
                    120:                                                        <TD>OpenBSD</TD>
                    121:                                                        <TD>
                    122:                                                        <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
                    123:                                                                CLASS="external">src/usr.bin/mandoc</A>
                    124:                                                        </TD>
                    125:                                                </TR>
                    126:                                        </TBODY>
                    127:                                        </TABLE>
1.1       kristaps  128:
1.40      kristaps  129:                                        <H2>
1.22      kristaps  130:                                        Historical
1.40      kristaps  131:                                        </H2>
1.10      kristaps  132:
1.40      kristaps  133:                                        <TABLE WIDTH="100%" SUMMARY="Archived Sources">
                    134:                                        <COL WIDTH="200">
                    135:                                        <COL>
                    136:                                        <TBODY>
                    137:                                                <TR>
                    138:                                                        <TD>Source archive</TD>
                    139:                                                        <TD>
                    140:                                                        <A HREF="/snapshots/">/snapshots/</A>
                    141:                                                        </TD>
                    142:                                                </TR>
                    143:                                        </TBODY>
                    144:                                        </TABLE>
                    145:                                </TD>
                    146:                        </TR>
                    147:                        <TR>
                    148:                                <TD>
                    149:                                        <H1>
1.18      kristaps  150:                                        DOCUMENTATION
1.40      kristaps  151:                                        </H1>
1.18      kristaps  152:
1.40      kristaps  153:                                        <P>
1.39      kristaps  154:                                        These manuals are generated automatically and refer to the current snapshot.
1.40      kristaps  155:                                        </P>
1.24      kristaps  156:
1.40      kristaps  157:                                        <TABLE WIDTH="100%" SUMMARY="Documentation">
                    158:                                        <COL WIDTH="200">
                    159:                                        <COL>
                    160:                                        <TBODY>
                    161:                                                <TR>
                    162:                                                        <TD><A HREF="mandoc.1.html">mandoc(1)</A> (<A HREF="mandoc.1.txt">text</A>)</TD>
                    163:                                                        <TD>format and display UNIX manuals</TD>
                    164:                                                </TR>
                    165:                                                <TR>
                    166:                                                        <TD><A HREF="mandoc_char.7.html">mandoc_char(7)</A> (<A HREF="mandoc_char.7.txt">text</A>)</TD>
                    167:                                                        <TD>mandoc special characters</TD>
                    168:                                                </TR>
                    169:                                                <TR>
                    170:                                                        <TD><A HREF="mdoc.7.html">mdoc(7)</A> (<A HREF="mdoc.7.txt">text</A>)</TD>
                    171:                                                        <TD>mdoc language reference</TD>
                    172:                                                </TR>
                    173:                                                <TR>
                    174:                                                        <TD><A HREF="man.7.html">man(7)</A> (<A HREF="man.7.txt">text</A>)</TD>
                    175:                                                        <TD>man language reference</TD>
                    176:                                                </TR>
                    177:                                                <TR>
                    178:                                                        <TD><A HREF="manuals.7.html">manuals(7)</A> (<A HREF="manuals.7.txt">text</A>)</TD>
                    179:                                                        <TD>a guide to writing UNIX manuals</TD>
                    180:                                                </TR>
                    181:                                                <TR>
                    182:                                                        <TD><A HREF="mdoc.3.html">mdoc(3)</A> (<A HREF="mdoc.3.txt">text</A>)</TD>
                    183:                                                        <TD>mdoc macro compiler library</TD>
                    184:                                                </TR>
                    185:                                                <TR>
                    186:                                                        <TD><A HREF="man.3.html">man(3)</A> (<A HREF="man.3.txt">text</A>)</TD>
                    187:                                                        <TD>man macro compiler library</TD>
                    188:                                                </TR>
                    189:                                        </TBODY>
                    190:                                        </TABLE>
                    191:                                </TD>
                    192:                        </TR>
                    193:                        <TR>
                    194:                                <TD>
                    195:                                        <H1>
1.1       kristaps  196:                                        CONTACT
1.40      kristaps  197:                                        </H1>
1.1       kristaps  198:
1.40      kristaps  199:                                        <P>
                    200:                                        For all issues related to <SPAN CLASS="nm">mdocml</SPAN>, contact Kristaps Dzonsons, kris<A
                    201:                                        CLASS="external"
                    202:                                        HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q=="
                    203:                                        TITLE="Reveal this e-mail address">...</A>@bsd.lv.
                    204:                                        </P>
1.18      kristaps  205:
1.40      kristaps  206:                                        <P>
1.61      kristaps  207:                                        You may also subscribe to several mailing lists (these require subscription, which is moderated):
1.40      kristaps  208:                                        </P>
1.57      kristaps  209:
                    210:                                        <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
                    211:                                                <COL WIDTH="200">
                    212:                                                <COL>
                    213:                                                <TBODY>
                    214:                                                        <TR>
                    215:                                                                <TD>
1.60      kristaps  216:                                                                        disc<A CLASS="external" TITLE="Reveal this e-mail address"
1.59      kristaps  217:                                                                        HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</a>@mdocml.bsd.lv
1.57      kristaps  218:                                                                </TD>
1.59      kristaps  219:                                                                <TD>discussions and announcements</TD>
1.58      kristaps  220:                                                        </TR>
1.63      kristaps  221:                                                        <!--<TR>
1.58      kristaps  222:                                                                <TD>
                    223:                                                                        sou<A CLASS="external" TITLE="Reveal this e-mail address"
                    224:                                                                        HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</a>@mdocml.bsd.lv
                    225:                                                                </TD>
1.59      kristaps  226:                                                                <TD>source commit messages</TD>
1.63      kristaps  227:                                                        </TR>-->
1.57      kristaps  228:                                                </TBODY>
                    229:                                        </TABLE>
1.40      kristaps  230:                                </TD>
                    231:                        </TR>
                    232:                        <TR>
                    233:                                <TD>
                    234:                                        <H1>
                    235:                                        NEWS
                    236:                                        </H1>
                    237:
                    238:                                        <TABLE WIDTH="100%" CELLPADDING="2">
1.42      kristaps  239:                                                <COL CLASS="date">
1.40      kristaps  240:                                                <TBODY>
                    241:                                                        <TR>
1.59      kristaps  242:                                                                <TD VALIGN="top"><SPAN CLASS="date">09-05-2010</SPAN></TD>
1.53      kristaps  243:                                                                <TD VALIGN="top">
1.64    ! kristaps  244:                                                                Fixed handling of <Q>\*(Ba</Q> escape.  Backed out <SPAN
        !           245:                                                                CLASS="flag">-fno-ign-chars</SPAN> (pointless complexity).
        !           246:                                                                Version: <SPAN CLASS="rev">1.9.24</SPAN>.
        !           247:                                                        </TR>
        !           248:                                                        <TR>
        !           249:                                                                <TD VALIGN="top"><SPAN CLASS="date">09-05-2010</SPAN></TD>
        !           250:                                                                <TD VALIGN="top">
1.59      kristaps  251:                                                                Rolled back break-at-hyphen.  <SPAN CLASS="flag">-DUGLY</SPAN> is now the
                    252:                                                                default (no feature splits!).  Free-form text is not de-chunked any more: lines
                    253:                                                                are passed whole-sale into the front-end, including whitespace.  Added mailing
                    254:                                                                lists.  Lastly, <SPAN CLASS="nm">mdocml</SPAN> is the focus of two <A
                    255:                                                                CLASS="external" HREF="http://socghop.appspot.com/">Google Summer of Code</A>
                    256:                                                                projects this year: <Q><A CLASS="external"
                    257:                                                                HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">mandoc -Tps</A></Q>
                    258:                                                                (NetBSD) and <Q><A CLASS="external"
                    259:                                                                HREF="http://wiki.freebsd.org/SummerOfCode2010Projects">BSD-licensed
                    260:                                                                Text-Processing Tools</A></Q> (FreeBSD).
1.53      kristaps  261:                                                                Version: <SPAN CLASS="rev">1.9.24</SPAN>.
                    262:                                                                </TD>
                    263:                                                        </TR>
                    264:
                    265:                                                        <TR>
1.51      kristaps  266:                                                                <TD VALIGN="top"><SPAN CLASS="date">07-04-2010</SPAN></TD>
1.50      kristaps  267:                                                                <TD VALIGN="top">
                    268:                                                                <SPAN CLASS="nm">mdocml</SPAN> has been linked to the <A CLASS="external"
                    269:                                                                HREF="http://www.openbsd.org/faq/current.html#20100403">OpenBSD build</a>.  This
                    270:                                                                version incorporates many small changes, mostly from patches by OpenBSD,
                    271:                                                                allowing crufty manuals to slip by with warnings instead of erroring-out.  Some
                    272:                                                                subtle semantic issues, such as punctuation scope, have also been fixed.
                    273:                                                                Lastly, some issues with <SPAN CLASS="flag">-Thtml</SPAN> have been fixed, which
                    274:                                                                prompted an update to the <A HREF="mandoc.1.html">online</A> <A
                    275:                                                                HREF="mandoc_char.7.html">manual</A> <A HREF="man.7.html">pages</A> style
1.52      kristaps  276:                                                                layout.  Version: <SPAN CLASS="rev">1.9.23</SPAN>.
1.50      kristaps  277:                                                                </TD>
                    278:                                                        </TR>
                    279:                                                        <TR>
1.49      kristaps  280:                                                                <TD VALIGN="top"><SPAN CLASS="date">31-03-2010</SPAN></TD>
                    281:                                                                <TD VALIGN="top">
                    282:                                                                Version <SPAN CLASS="rev">1.9.22</SPAN>: adjusted merge of the significant work
                    283:                                                                by Ingo Schwarze in getting <Q>Xo</Q> blocks (block full implicit, e.g.,
                    284:                                                                <Q>It</Q> for non-columnar lists) to work properly.  This isn't enabled by
                    285:                                                                default: you must specify <SPAN CLASS="flag">-DUGLY</SPAN> as a compiler flag
                    286:                                                                (see the Makefile for details).
                    287:                                                                </TD>
                    288:                                                        </TR>
                    289:                                                        <TR>
1.48      kristaps  290:                                                                <TD VALIGN="top"><SPAN CLASS="date">30-03-2010</SPAN></TD>
1.47      kristaps  291:                                                                <TD VALIGN="top">
                    292:                                                                Version <SPAN CLASS="rev">1.9.20</SPAN>: more efforts to get roff instructions
1.48      kristaps  293:                                                                in -man documents under control.  Note that roff instructions embedded in
                    294:                                                                line-scoped, next-line macros (e.g. <Q>B</Q>) are not supported.  Leading
                    295:                                                                punctuation for -mdoc macros, such as <Q>Fl ( ( a</Q>, are now correctly
                    296:                                                                handled.
1.47      kristaps  297:                                                                </TD>
                    298:                                                        </TR>
                    299:                                                        <TR>
1.46      kristaps  300:                                                                <TD VALIGN="top"><SPAN CLASS="date">27-03-2010</SPAN></TD>
                    301:                                                                <TD VALIGN="top">
                    302:                                                                Version <SPAN CLASS="rev">1.9.18</SPAN>: many fixes (largely pertaining to
                    303:                                                                scope) and improvements (e.g., handling of apostrophe-control macros, which
                    304:                                                                fixes the strange <Q>BR</Q> seen in some macro output) to handling roff
                    305:                                                                instructions in -man documents.
                    306:                                                                </TD>
                    307:                                                        </TR>
                    308:                                                        <TR>
1.45      kristaps  309:                                                                <TD VALIGN="top"><SPAN CLASS="date">25-03-2010</SPAN></TD>
1.43      kristaps  310:                                                                <TD VALIGN="top">
1.45      kristaps  311:                                                                Version <SPAN CLASS="rev">1.9.17</SPAN> highlights: accept <A
                    312:                                                                HREF="http://perldoc.perl.org/" CLASS="external">perlpod</A> standard preamble.
                    313:                                                                Also accept (and discard) <Q>de</Q>, <Q>dei</Q>, <Q>am</Q>, <Q>ami</Q>, and
                    314:                                                                <Q>ig</Q> roff macro blocks.
1.43      kristaps  315:                                                                </TD>
                    316:                                                        </TR>
                    317:                                                        <TR>
1.42      kristaps  318:                                                                <TD VALIGN="top"><SPAN CLASS="date">22-03-2010</SPAN></TD>
                    319:                                                                <TD VALIGN="top">
                    320:                                                                Version <SPAN CLASS="rev">1.9.16</SPAN> highlights: inspired by patches and bug
                    321:                                                                reports by Ingo Schwarze, allowed <SPAN CLASS="flag">-man</SPAN> to accept
                    322:                                                                non-printing elements to be nested within next-line scopes, such as <Q>br</Q>
                    323:                                                                within <Q>B</Q> or <Q>TH</Q>, which is valid roff.  Longsoon architecture also
                    324:                                                                noted and Makefile cleaned up.
                    325:                                                                </TD>
                    326:                                                        </TR>
                    327:                                                        <TR>
1.41      kristaps  328:                                                                <TD VALIGN="top"><SPAN CLASS="date">18-02-2010</SPAN></TD>
1.40      kristaps  329:                                                                <TD VALIGN="top">
                    330:                                                                Moved to our new <A HREF="http://bsd.lv" CLASS="external">BSD.lv</A> home.
1.41      kristaps  331:                                                                Version <SPAN CLASS="rev">1.9.15</SPAN> highlights: XHTML is now an acceptable
                    332:                                                                output mode for <A HREF="mandoc.1.html">mandoc(1)</A>;  <Q>Xr</Q> made more
                    333:                                                                compatible with groff; <Q>Vt</Q> fixed when invoked in SYNOPSIS;  <Q>\\</Q>
                    334:                                                                escape removed; end-of-line white-space detected for all lines;  subtle bug
                    335:                                                                fixed in list display for some modes;  compatibility layer checked in for
                    336:                                                                compilation in diverse UNIX systems;  and column lengths handled correctly.
1.40      kristaps  337:                                                                </TD>
                    338:                                                        </TR>
                    339:                                                </TBODY>
                    340:                                        </TABLE>
                    341:                                </TD>
                    342:                        </TR>
                    343:                        <TR>
                    344:                                <TD>
                    345:                                        <DIV CLASS="foot">
1.64    ! kristaps  346:                                                Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2010/05/09 06:50:23 $
1.40      kristaps  347:                                        </DIV>
                    348:                                </TD>
                    349:                        </TR>
                    350:                </TBODY>
                    351:        </TABLE>
                    352:        </BODY>
                    353: </HTML>

CVSweb