index.sgml

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   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">
   7                 <TITLE>mdocml | mdoc macro compiler</TITLE>
   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                                         <DIV CLASS="subhead">
  19                                                 <A HREF="#description">Description</A> |
  20                                                 <A HREF="#sources">Sources</A> |
  21                                                 <A HREF="#documentation">Documentation</A> |
  22                                                 <A HREF="#contact">Contact</A> |
  23                                                 <A HREF="#news">News</A>
  24                                         </DIV>
  25                                 </TD>
  26                         </TR>
  27                         <TR>
  28                                 <TD VALIGN="top">
  29                                         <H1>
  30                                         <A NAME="description">DESCRIPTION</A>
  31                                         </H1>
  32
  33                                         <P>
  34                                         <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <Q>-mdoc</Q>, the roff macro package
  35                                         of choice for BSD manual pages, and <Q>-man</Q>, the predominant historical package for UNIX
  36                                         manuals.  The mission of <SPAN CLASS="nm">mdocml</SPAN> is to deprecate <A
  37                                         HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU roff implementation, for
  38                                         displaying -mdoc pages whilst providing token support for -man.
  39                                         </P>
  40
  41                                         <P>
  42                                         Why?  groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL.  It runs
  43                                         slowly, produces uncertain output, and varies in operation from system to system.  mdocml strives to fix
  44                                         this (respectively small, C, ISC-licensed, fast and regular).
  45                                         </P>
  46
  47                                         <P>
  48                                         The core of <SPAN CLASS="nm">mdocml</SPAN> is composed of the <A HREF="mdoc.3.html">libmdoc</A>, <A
  49                                         HREF="man.3.html">libman</A>, and <A HREF="roff.3.html">libroff</A> validating compiler libraries.  All
  50                                         are simple, fast libraries operating on memory buffers, so they may be used for a variety of front-ends
  51                                         (terminal-based, CGI and so on).  The front-end is <A HREF="mandoc.1.html">mandoc</A>, which formats
  52                                         manuals for display.
  53                                         </P>
  54
  55                                         <P>
  56                                         The <SPAN CLASS="nm">mdocml</SPAN> suite is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv
  57                                         Project</A> member.
  58                                         </P>
  59                                 </TD>
  60                         </TR>
  61                         <TR>
  62                                 <TD>
  63                                         <H1>
  64                                         <A NAME="sources">SOURCES</A>
  65                                         </H1>
  66
  67                                         <P>
  68                                         Sources correctly build and install on DragonFly BSD, FreeBSD, OpenBSD, NetBSD, GNU/Linux, and many
  69                                         other operating systems, tested variously on i386, AMD64, alpha, and others.  The most current version
  70                                         is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>.  A full <A
  71                                         HREF="ChangeLog.html">ChangeLog</A> (<A HREF="ChangeLog.txt">txt</A>) is written with each release.
  72                                         </P>
  73
  74                                         <H2>
  75                                         Current
  76                                         </H2>
  77
  78                                         <TABLE WIDTH="100%" SUMMARY="Current Sources">
  79                                         <COL WIDTH="200">
  80                                         <COL>
  81                                         <TBODY>
  82                                                 <TR>
  83                                                         <TD>Source archive</TD>
  84                                                         <TD>
  85                                                         <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
  86                                                         (<A HREF="/snapshots/mdocml.md5">md5</A>)
  87                                                         </TD>
  88                                                 </TR>
  89                                                 <TR>
  90                                                         <TD>Online source</TD>
  91                                                         <TD>
  92                                                         <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
  93                                                         </TD>
  94                                                 </TR>
  95                                         </TBODY>
  96                                         </TABLE>
  97
  98                                         <H2>
  99                                         Downstream
 100                                         </H2>
 101
 102                                         <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
 103                                         <COL WIDTH="200">
 104                                         <COL>
 105                                         <TBODY>
 106                                                 <TR>
 107                                                         <TD>DragonFly BSD</TD>
 108                                                         <TD>
 109                                                         <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
 110                                                                 CLASS="external">usr.bin/mandoc</A>
 111                                                         </TD>
 112                                                 </TR>
 113                                                 <TR>
 114                                                         <TD>FreeBSD</TD>
 115                                                         <TD>
 116                                                         <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
 117                                                                 CLASS="external">ports/textproc/mdocml</A>
 118                                                         </TD>
 119                                                 </TR>
 120                                                 <TR>
 121                                                         <TD>NetBSD</TD>
 122                                                         <TD>
 123                                                         <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
 124                                                                 CLASS="external">src/external/bsd/mdocml</A>
 125                                                         </TD>
 126                                                 </TR>
 127                                                 <TR>
 128                                                         <TD>OpenBSD</TD>
 129                                                         <TD>
 130                                                         <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
 131                                                                 CLASS="external">src/usr.bin/mandoc</A>
 132                                                         </TD>
 133                                                 </TR>
 134                                         </TBODY>
 135                                         </TABLE>
 136
 137                                         <H2>
 138                                         Historical
 139                                         </H2>
 140
 141                                         <TABLE WIDTH="100%" SUMMARY="Archived Sources">
 142                                         <COL WIDTH="200">
 143                                         <COL>
 144                                         <TBODY>
 145                                                 <TR>
 146                                                         <TD>Source archive</TD>
 147                                                         <TD>
 148                                                         <A HREF="/snapshots/">/snapshots/</A>
 149                                                         </TD>
 150                                                 </TR>
 151                                         </TBODY>
 152                                         </TABLE>
 153                                 </TD>
 154                         </TR>
 155                         <TR>
 156                                 <TD>
 157                                         <H1>
 158                                         <A NAME="documentation">DOCUMENTATION</A>
 159                                         </H1>
 160
 161                                         <P>
 162                                         These manuals are generated automatically and refer to the current snapshot.
 163                                         </P>
 164
 165                                         <TABLE WIDTH="100%" SUMMARY="Documentation">
 166                                         <COL WIDTH="200">
 167                                         <COL>
 168                                         <TBODY>
 169                                                 <TR>
 170                                                         <TD VALIGN="top"><A HREF="man.3.html">man(3)</A></TD>
 171                                                         <TD VALIGN="top">
 172                                                                 man macro compiler library
 173                                                                 <DIV STYLE="font-size: smaller;">
 174                                                                         <A HREF="man.3.txt">text</A> | <A HREF="man.3.ps">postscript</A>
 175                                                                 </DIV>
 176                                                         </TD>
 177                                                 </TR>
 178                                                 <TR>
 179                                                         <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
 180                                                         <TD VALIGN="top">
 181                                                                 man language reference
 182                                                                 <DIV STYLE="font-size: smaller;">
 183                                                                         <A HREF="man.7.txt">text</A> | <A HREF="man.7.ps">postscript</A>
 184                                                                 </DIV>
 185                                                         </TD>
 186                                                 </TR>
 187                                                 <TR>
 188                                                         <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
 189                                                         <TD VALIGN="top">
 190                                                                 format and display UNIX manuals
 191                                                                 <DIV STYLE="font-size: smaller;">
 192                                                                         <A HREF="mandoc.1.txt">text</A> | <A HREF="mandoc.1.ps">postscript</A>
 193                                                                 </DIV>
 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                                                                 <DIV STYLE="font-size: smaller;">
 201                                                                         <A HREF="mandoc_char.7.txt">text</A> | <A HREF="mandoc_char.7.ps">postscript</A>
 202                                                                 </DIV>
 203                                                         </TD>
 204                                                 </TR>
 205                                                 <TR>
 206                                                         <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
 207                                                         <TD VALIGN="top">
 208                                                                 mdoc macro compiler library
 209                                                                 <DIV STYLE="font-size: smaller;">
 210                                                                         <A HREF="mdoc.3.txt">text</A> | <A HREF="mdoc.3.ps">postscript</A>
 211                                                                 </DIV>
 212                                                         </TD>
 213                                                 </TR>
 214                                                 <TR>
 215                                                         <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
 216                                                         <TD VALIGN="top">
 217                                                                 mdoc language reference
 218                                                                 <DIV STYLE="font-size: smaller;">
 219                                                                         <A HREF="mdoc.7.txt">text</A> | <A HREF="mdoc.7.ps">postscript</A>
 220                                                                 </DIV>
 221                                                         </TD>
 222                                                 </TR>
 223                                                 <TR>
 224                                                         <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
 225                                                         <TD VALIGN="top">
 226                                                                 roff macro compiler library
 227                                                                 <DIV STYLE="font-size: smaller;">
 228                                                                         <A HREF="roff.3.txt">text</A> | <A HREF="roff.3.ps">postscript</A>
 229                                                                 </DIV>
 230                                                         </TD>
 231                                                 </TR>
 232                                                 <TR>
 233                                                         <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
 234                                                         <TD VALIGN="top">
 235                                                                 roff-mandoc language reference
 236                                                                 <DIV STYLE="font-size: smaller;">
 237                                                                         <A HREF="roff.7.txt">text</A> | <A HREF="roff.7.ps">postscript</A>
 238                                                                 </DIV>
 239                                                         </TD>
 240                                                 </TR>
 241                                         </TBODY>
 242                                         </TABLE>
 243
 244                                         <P>
 245                                         See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
 246                                         introduction to manpages and mdoc.
 247                                         </P>
 248                                 </TD>
 249                         </TR>
 250                         <TR>
 251                                 <TD>
 252                                         <H1>
 253                                         <A NAME="contact">CONTACT</A>
 254                                         </H1>
 255
 256                                         <P>
 257                                         For all issues related to <SPAN CLASS="nm">mdocml</SPAN>, contact Kristaps Dzonsons, kris<A
 258                                         CLASS="external"
 259                                         HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q=="
 260                                         TITLE="Reveal this e-mail address">...</A>@bsd.lv.
 261                                         </P>
 262
 263                                         <P>
 264                                         You may also subscribe to several mailing lists (these require subscription, which is moderated).  An
 265                                         archive is not yet available on-line, although you may request one once subscribed.
 266                                         </P>
 267
 268                                         <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
 269                                                 <COL WIDTH="200">
 270                                                 <COL>
 271                                                 <TBODY>
 272                                                         <TR>
 273                                                                 <TD>
 274                                                                         disc<A CLASS="external" TITLE="Reveal this e-mail address"
 275                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
 276                                                                 </TD>
 277                                                                 <TD>high-level discussions and version announcements</TD>
 278                                                         </TR>
 279                                                         <TR>
 280                                                                 <TD>
 281                                                                         tec<A CLASS="external" TITLE="Reveal this e-mail address"
 282                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&amp;c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
 283                                                                 </TD>
 284                                                                 <TD>low-level discussions</TD>
 285                                                         </TR>
 286                                                         <TR>
 287                                                                 <TD>
 288                                                                         sou<A CLASS="external" TITLE="Reveal this e-mail address"
 289                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
 290                                                                 </TD>
 291                                                                 <TD>source commit messages</TD>
 292                                                         </TR>
 293                                                 </TBODY>
 294                                         </TABLE>
 295                                 </TD>
 296                         </TR>
 297                         <TR>
 298                                 <TD>
 299                                         <H1>
 300                                         <A NAME="news">NEWS</A>
 301                                         </H1>
 302                                         <DIV CLASS="news">
 303                                                 <P>
 304                                                         <SPAN CLASS="date">19-06-2010</SPAN>:
 305                                                         version 1.10.2
 306                                                 </P>
 307                                                 <P>
 308                                                         Small release featuring text-decoration in <SPAN CLASS="flag">-Tps</SPAN> output, a few
 309                                                         minor relaxations of errors, and some optimisations.
 310                                                 </P>
 311                                         </DIV>
 312                                         <DIV CLASS="news">
 313                                                 <P>
 314                                                         <SPAN CLASS="date">07-06-2010</SPAN>:
 315                                                         version 1.10.1
 316                                                 </P>
 317                                                 <P>
 318                                                         This primarily focusses on the <Q>Bl</Q> and <Q>It</Q> macros described in <A
 319                                                         HREF="mdoc.7.html">mdoc</A>.  Multi-line column support is now fully compatible with
 320                                                         groff, as are implicit list entries for columns.  Removed manuals.7 in favour of <A
 321                                                         CLASS="external" HREF="http://manpages.bsd.lv">http://manpages.bsd.lv</A>.  The way we
 322                                                         handle the SYNOPSIS section (see the SYNOPSIS documentation in <A
 323                                                         HREF="mdoc.7.html#x4d414e55414cx20x535452554354555245">MANUAL STRUCTURE</A>) has also
 324                                                         been considerably simplified compared to groff's method.  Furthermore, the <SPAN
 325                                                         CLASS="flag">-Owidth=width</SPAN> output option has been added to <SPAN
 326                                                         CLASS="flag">-Tascii</SPAN> (see <A HREF="mandoc.1.html">mandoc</A>).  Lastly, initial
 327                                                         PostScript output has been added with the <SPAN CLASS="flag">-Tps</SPAN> option to <A
 328                                                         HREF="mandoc.1.html">mandoc</A>.  It's brutally simple at the moment: fixed-font, with
 329                                                         no font decorations.
 330                                                 </P>
 331                                         </DIV>
 332                                         <DIV CLASS="news">
 333                                                 <P>
 334                                                         <SPAN CLASS="date">29-05-2010</SPAN>:
 335                                                         version 1.10.0
 336                                                 </P>
 337                                                 <P>
 338                                                         Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD.
 339                                                         This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg
 340                                                         Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10.
 341                                                         Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:
 342                                                 </P>
 343                                                 <UL>
 344                                                         <LI>a <A HREF="roff.3.html">libroff</A> preprocessor in front of <A
 345                                                         HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> stripping out
 346                                                         <A HREF="roff.7.html">roff</A> instructions;</LI>
 347                                                         <LI>end-of-sentence (EOS) detection in free-form and macro lines;</LI>
 348                                                         <LI>correct handling of tab-separated columnar lists in <SPAN
 349                                                         CLASS="flag">-mdoc</SPAN>;</LI>
 350                                                         <LI>improved main calling routines to optionally use mmap() for better
 351                                                         performance;</LI>
 352                                                         <LI>cleaned up exiting when invoked as <SPAN CLASS="flag">-Tlint</SPAN> or over
 353                                                         multiple files with <SPAN CLASS="flag">-fign-errors</SPAN>;</LI>
 354                                                         <LI>error and warning message handling re-written to be unified for <A
 355                                                         HREF="roff.3.html">libroff</A>, <A HREF="mdoc.3.html">libmdoc</A>, and <A
 356                                                         HREF="man.3.html">libman</A>;</LI>
 357                                                         <LI>handling of badly-nested explicit-scoped macros;</LI>
 358                                                         <LI>improved free-form text parsing in <A HREF="man.3.html">libman</A> and <A
 359                                                         HREF="mdoc.3.html">libmdoc</A>;</LI>
 360                                                         <LI>significant GNU troff compatibility improvements in <SPAN
 361                                                         CLASS="flag">-Tascii</SPAN>, largely in terms of spacing;</LI>
 362                                                         <LI>a regression framework for making sure the many fragilities of GNU troff
 363                                                         aren't trampled in subsequent work;</LI>
 364                                                         <LI>support for <SPAN CLASS="flag">-Tascii</SPAN> breaking at hyphens
 365                                                         encountered in free-form text;</LI>
 366                                                         <LI>and many more minor fixes and improvements (no really, consult <A
 367                                                         HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> and see
 368                                                         for yourself!).</LI>
 369                                                 </UL>
 370                                         </DIV>
 371                                         <DIV CLASS="news">
 372                                                 <P>
 373                                                         <SPAN CLASS="date">13-05-2010</SPAN>:
 374                                                         version 1.9.25
 375                                                 </P>
 376                                                 <P>
 377                                                         Fixed handling of <Q>\*(Ba</Q> escape.  Backed out <SPAN
 378                                                         CLASS="flag">-fno-ign-chars</SPAN> (pointless complexity).  Fixed erroneous
 379                                                         breaking of literal lines.  Fixed SYNOPSIS breaking lines before non-initial
 380                                                         macros.  Changed default section ordering.  Most importantly, the framework for
 381                                                         end-of-sentence double-spacing is in place, now implemented for the
 382                                                         <Q>end-of-sentence, end-of-line</Q> rule.  This is a stable roll-back point
 383                                                         before the mandoc hackathon in Rostock!
 384                                                 </P>
 385                                         </DIV>
 386                                         <DIV CLASS="news">
 387                                                 <P>
 388                                                         <SPAN CLASS="date">09-05-2010</SPAN>:
 389                                                         version 1.9.24
 390                                                 </P>
 391                                                 <P>
 392                                                         Rolled back break-at-hyphen.  <SPAN CLASS="flag">-DUGLY</SPAN> is now the
 393                                                         default (no feature splits!).  Free-form text is not de-chunked any more: lines
 394                                                         are passed whole-sale into the front-end, including whitespace.  Added mailing
 395                                                         lists.  Lastly, <SPAN CLASS="nm">mdocml</SPAN> is the focus of two <A
 396                                                         CLASS="external" HREF="http://socghop.appspot.com/">Google Summer of Code</A>
 397                                                         projects this year: <Q><A CLASS="external"
 398                                                         HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">mandoc -Tps</A></Q>
 399                                                         (NetBSD) and <Q><A CLASS="external"
 400                                                         HREF="http://wiki.freebsd.org/SummerOfCode2010Projects">BSD-licensed
 401                                                         Text-Processing Tools</A></Q> (FreeBSD).
 402                                                 </P>
 403                                         </DIV>
 404                                         <P>
 405                                                 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
 406                                                 historical notes.
 407                                         </P>
 408                                 </TD>
 409                         </TR>
 410                         <TR>
 411                                 <TD>
 412                                         <DIV CLASS="foot">
 413                                                 Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2010/06/19 20:43:35 $
 414                                         </DIV>
 415                                 </TD>
 416                         </TR>
 417                 </TBODY>
 418         </TABLE>
 419         </BODY>
 420 </HTML>