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><A HREF="man.3.html">man(3)</A> (<A HREF="man.3.txt">text</A>)</TD>
 171                                                         <TD>man macro compiler library</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="mandoc.1.html">mandoc(1)</A> (<A HREF="mandoc.1.txt">text</A>)</TD>
 179                                                         <TD>format and display UNIX manuals</TD>
 180                                                 </TR>
 181                                                 <TR>
 182                                                         <TD><A HREF="mandoc_char.7.html">mandoc_char(7)</A> (<A HREF="mandoc_char.7.txt">text</A>)</TD>
 183                                                         <TD>mandoc special characters</TD>
 184                                                 </TR>
 185                                                 <TR>
 186                                                         <TD><A HREF="manuals.7.html">manuals(7)</A> (<A HREF="manuals.7.txt">text</A>)</TD>
 187                                                         <TD>a guide to writing UNIX manuals</TD>
 188                                                 </TR>
 189                                                 <TR>
 190                                                         <TD><A HREF="mdoc.3.html">mdoc(3)</A> (<A HREF="mdoc.3.txt">text</A>)</TD>
 191                                                         <TD>mdoc macro compiler library</TD>
 192                                                 </TR>
 193                                                 <TR>
 194                                                         <TD><A HREF="mdoc.7.html">mdoc(7)</A> (<A HREF="mdoc.7.txt">text</A>)</TD>
 195                                                         <TD>mdoc language reference</TD>
 196                                                 </TR>
 197                                                 <TR>
 198                                                         <TD><A HREF="roff.3.html">roff(3)</A> (<A HREF="roff.3.txt">text</A>)</TD>
 199                                                         <TD>roff macro compiler library</TD>
 200                                                 </TR>
 201                                                 <TR>
 202                                                         <TD><A HREF="roff.7.html">roff(7)</A> (<A HREF="roff.7.txt">text</A>)</TD>
 203                                                         <TD>roff-mandoc language reference</TD>
 204                                                 </TR>
 205                                         </TBODY>
 206                                         </TABLE>
 207                                 </TD>
 208                         </TR>
 209                         <TR>
 210                                 <TD>
 211                                         <H1>
 212                                         <A NAME="contact">CONTACT</A>
 213                                         </H1>
 214
 215                                         <P>
 216                                         For all issues related to <SPAN CLASS="nm">mdocml</SPAN>, contact Kristaps Dzonsons, kris<A
 217                                         CLASS="external"
 218                                         HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q=="
 219                                         TITLE="Reveal this e-mail address">...</A>@bsd.lv.
 220                                         </P>
 221
 222                                         <P>
 223                                         You may also subscribe to several mailing lists (these require subscription, which is moderated).  An
 224                                         archive is not yet available on-line, although you may request one once subscribed.
 225                                         </P>
 226
 227                                         <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
 228                                                 <COL WIDTH="200">
 229                                                 <COL>
 230                                                 <TBODY>
 231                                                         <TR>
 232                                                                 <TD>
 233                                                                         disc<A CLASS="external" TITLE="Reveal this e-mail address"
 234                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
 235                                                                 </TD>
 236                                                                 <TD>high-level discussions and version announcements</TD>
 237                                                         </TR>
 238                                                         <TR>
 239                                                                 <TD>
 240                                                                         tec<A CLASS="external" TITLE="Reveal this e-mail address"
 241                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&amp;c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
 242                                                                 </TD>
 243                                                                 <TD>low-level discussions</TD>
 244                                                         </TR>
 245                                                         <TR>
 246                                                                 <TD>
 247                                                                         sou<A CLASS="external" TITLE="Reveal this e-mail address"
 248                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
 249                                                                 </TD>
 250                                                                 <TD>source commit messages</TD>
 251                                                         </TR>
 252                                                 </TBODY>
 253                                         </TABLE>
 254                                 </TD>
 255                         </TR>
 256                         <TR>
 257                                 <TD>
 258                                         <H1>
 259                                         <A NAME="news">NEWS</A>
 260                                         </H1>
 261
 262                                         <DIV CLASS="news">
 263                                                 <P>
 264                                                         <SPAN CLASS="date">29-05-2010</SPAN>:
 265                                                         version 1.10.0
 266                                                 </P>
 267                                                 <P>
 268                                                         Release consisting of the results from the m2k10 hackathon and up-merge from OpenBSD.
 269                                                         This requires a significant note of thanks to Ingo Schwarze (OpenBSD) and Joerg
 270                                                         Sonnenberger (NetBSD) for their hard work, and again to Joerg for hosting m2k10.
 271                                                         Highlights (mostly cribbed from Ingo's m2k10 report) follow in no particular order:
 272                                                 </P>
 273                                                 <UL>
 274                                                         <LI>a <A HREF="roff.3.html">libroff</A> preprocessor in front of <A
 275                                                         HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> stripping out
 276                                                         <A HREF="roff.7.html">roff</A> instructions;</LI>
 277                                                         <LI>end-of-sentence (EOS) detection in free-form and macro lines;</LI>
 278                                                         <LI>correct handling of tab-separated columnar lists in <SPAN
 279                                                         CLASS="flag">-mdoc</SPAN>;</LI>
 280                                                         <LI>improved main calling routines to optionally use mmap() for better
 281                                                         performance;</LI>
 282                                                         <LI>cleaned up exiting when invoked as <SPAN CLASS="flag">-Tlint</SPAN> or over
 283                                                         multiple files with <SPAN CLASS="flag">-fign-errors</SPAN>;</LI>
 284                                                         <LI>error and warning message handling re-written to be unified for <A
 285                                                         HREF="roff.3.html">libroff</A>, <A HREF="mdoc.3.html">libmdoc</A>, and <A
 286                                                         HREF="man.3.html">libman</A>;</LI>
 287                                                         <LI>handling of badly-nested explicit-scoped macros;</LI>
 288                                                         <LI>improved free-form text parsing in <A HREF="man.3.html">libman</A> and <A
 289                                                         HREF="mdoc.3.html">libmdoc</A>;</LI>
 290                                                         <LI>significant GNU troff compatibility improvements in <SPAN
 291                                                         CLASS="flag">-Tascii</SPAN>, largely in terms of spacing;</LI>
 292                                                         <LI>a regression framework for making sure the many fragilities of GNU troff
 293                                                         aren't trampled in subsequent work;</LI>
 294                                                         <LI>support for <SPAN CLASS="flag">-Tascii</SPAN> breaking at hyphens
 295                                                         encountered in free-form text;</LI>
 296                                                         <LI>and many more minor fixes and improvements (no really, consult <A
 297                                                         HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A> and see
 298                                                         for yourself!).</LI>
 299                                                 </UL>
 300                                         </DIV>
 301                                         <DIV CLASS="news">
 302                                                 <P>
 303                                                         <SPAN CLASS="date">13-05-2010</SPAN>:
 304                                                         version 1.9.25
 305                                                 </P>
 306                                                 <P>
 307                                                         Fixed handling of <Q>\*(Ba</Q> escape.  Backed out <SPAN
 308                                                         CLASS="flag">-fno-ign-chars</SPAN> (pointless complexity).  Fixed erroneous
 309                                                         breaking of literal lines.  Fixed SYNOPSIS breaking lines before non-initial
 310                                                         macros.  Changed default section ordering.  Most importantly, the framework for
 311                                                         end-of-sentence double-spacing is in place, now implemented for the
 312                                                         <Q>end-of-sentence, end-of-line</Q> rule.  This is a stable roll-back point
 313                                                         before the mandoc hackathon in Rostock!
 314                                                 </P>
 315                                         </DIV>
 316                                         <DIV CLASS="news">
 317                                                 <P>
 318                                                         <SPAN CLASS="date">09-05-2010</SPAN>:
 319                                                         version 1.9.24
 320                                                 </P>
 321                                                 <P>
 322                                                         Rolled back break-at-hyphen.  <SPAN CLASS="flag">-DUGLY</SPAN> is now the
 323                                                         default (no feature splits!).  Free-form text is not de-chunked any more: lines
 324                                                         are passed whole-sale into the front-end, including whitespace.  Added mailing
 325                                                         lists.  Lastly, <SPAN CLASS="nm">mdocml</SPAN> is the focus of two <A
 326                                                         CLASS="external" HREF="http://socghop.appspot.com/">Google Summer of Code</A>
 327                                                         projects this year: <Q><A CLASS="external"
 328                                                         HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">mandoc -Tps</A></Q>
 329                                                         (NetBSD) and <Q><A CLASS="external"
 330                                                         HREF="http://wiki.freebsd.org/SummerOfCode2010Projects">BSD-licensed
 331                                                         Text-Processing Tools</A></Q> (FreeBSD).
 332                                                 </P>
 333                                         </DIV>
 334
 335                                         <DIV CLASS="news">
 336                                                 <P>
 337                                                         <SPAN CLASS="date">07-04-2010</SPAN>:
 338                                                         version 1.9.23
 339                                                 </P>
 340                                                 <P>
 341                                                         <SPAN CLASS="nm">mdocml</SPAN> has been linked to the <A CLASS="external"
 342                                                         HREF="http://www.openbsd.org/faq/current.html#20100403">OpenBSD build</a>.  This
 343                                                         version incorporates many small changes, mostly from patches by OpenBSD,
 344                                                         allowing crufty manuals to slip by with warnings instead of erroring-out.  Some
 345                                                         subtle semantic issues, such as punctuation scope, have also been fixed.
 346                                                         Lastly, some issues with <SPAN CLASS="flag">-Thtml</SPAN> have been fixed, which
 347                                                         prompted an update to the <A HREF="mandoc.1.html">online</A> <A
 348                                                         HREF="mandoc_char.7.html">manual</A> <A HREF="man.7.html">pages</A> style
 349                                                         layout.
 350                                                 </P>
 351                                         </DIV>
 352                                         <P>
 353                                                 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
 354                                                 historical notes.
 355                                         </P>
 356                                 </TD>
 357                         </TR>
 358                         <TR>
 359                                 <TD>
 360                                         <DIV CLASS="foot">
 361                                                 Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2010/05/30 10:36:10 $
 362                                         </DIV>
 363                                 </TD>
 364                         </TR>
 365                 </TBODY>
 366         </TABLE>
 367         </BODY>
 368 </HTML>