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                                 </TD>
  19                         </TR>
  20                         <TR>
  21                                 <TD VALIGN="top">
  22                                         <H1>
  23                                         DESCRIPTION
  24                                         </H1>
  25
  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
  31                                         displaying -mdoc pages whilst providing token support for -man.
  32                                         </P>
  33
  34                                         <P>
  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).
  38                                         </P>
  39
  40                                         <P>
  41                                         The core of <SPAN CLASS="nm">mdocml</SPAN> is composed of the <i>libmdoc</i> and <i>libman</i>
  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.
  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>
  56                                         SOURCES
  57                                         </H1>
  58
  59                                         <P>
  60                                         Sources correctly build and install on DragonFly BSD, FreeBSD, OpenBSD, NetBSD, and GNU/Linux operating
  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>
  65
  66                                         <H2>
  67                                         Current
  68                                         </H2>
  69
  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>
  89
  90                                         <H2>
  91                                         Downstream
  92                                         </H2>
  93
  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>
 128
 129                                         <H2>
 130                                         Historical
 131                                         </H2>
 132
 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>
 150                                         DOCUMENTATION
 151                                         </H1>
 152
 153                                         <P>
 154                                         These manuals are generated automatically and refer to the current snapshot.
 155                                         </P>
 156
 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                                                 <TR>
 190                                                         <TD><A HREF="roff.7.html">roff(7)</A> (<A HREF="roff.7.txt">text</A>)</TD>
 191                                                         <TD>roff language reference</TD>
 192                                                 </TR>
 193                                         </TBODY>
 194                                         </TABLE>
 195                                 </TD>
 196                         </TR>
 197                         <TR>
 198                                 <TD>
 199                                         <H1>
 200                                         CONTACT
 201                                         </H1>
 202
 203                                         <P>
 204                                         For all issues related to <SPAN CLASS="nm">mdocml</SPAN>, contact Kristaps Dzonsons, kris<A
 205                                         CLASS="external"
 206                                         HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q=="
 207                                         TITLE="Reveal this e-mail address">...</A>@bsd.lv.
 208                                         </P>
 209
 210                                         <P>
 211                                         You may also subscribe to several mailing lists (these require subscription, which is moderated).  An
 212                                         archive is not yet available.
 213                                         </P>
 214
 215                                         <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
 216                                                 <COL WIDTH="200">
 217                                                 <COL>
 218                                                 <TBODY>
 219                                                         <TR>
 220                                                                 <TD>
 221                                                                         disc<A CLASS="external" TITLE="Reveal this e-mail address"
 222                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</a>@mdocml.bsd.lv
 223                                                                 </TD>
 224                                                                 <TD>high-level discussions and version announcements</TD>
 225                                                         </TR>
 226                                                         <TR>
 227                                                                 <TD>
 228                                                                         tec<A CLASS="external" TITLE="Reveal this e-mail address"
 229                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=014mgcCKFE_qqo9NLETCAiEA==&amp;c=-y6beh3b_SMDe6Iauc3PW-c1wlVbRqYJdj1RETN9WMs=">...</a>@mdocml.bsd.lv
 230                                                                 </TD>
 231                                                                 <TD>low-level discussions</TD>
 232                                                         </TR>
 233                                                         <TR>
 234                                                                 <TD>
 235                                                                         sou<A CLASS="external" TITLE="Reveal this e-mail address"
 236                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</a>@mdocml.bsd.lv
 237                                                                 </TD>
 238                                                                 <TD>source commit messages</TD>
 239                                                         </TR>
 240                                                 </TBODY>
 241                                         </TABLE>
 242                                 </TD>
 243                         </TR>
 244                         <TR>
 245                                 <TD>
 246                                         <H1>
 247                                         NEWS
 248                                         </H1>
 249
 250                                         <TABLE WIDTH="100%" CELLPADDING="2">
 251                                                 <COL CLASS="date">
 252                                                 <TBODY>
 253                                                         <TR>
 254                                                                 <TD VALIGN="top"><SPAN CLASS="date">xx-05-2010</SPAN></TD>
 255                                                                 Day 1 of Rostock hackathon: proper handling of quotations in tab-separated
 256                                                                 column lists, finished patching of SYNOPSIS breaking (1.9.25), fixed pre-comment
 257                                                                 white-space stripping, added end-of-sentence spacing to black partial-implicit
 258                                                                 macros, relaxed column warnings, relaxed acceptence of bad standards arguments,
 259                                                                 significant documentation of lists in <A HREF="mdoc.7.html">mdoc(7)</A>.
 260                                                                 Version: <SPAN CLASS="rev">1.9.26</SPAN>.
 261                                                                 <TD VALIGN="top">
 262                                                         </TR>
 263                                                         <TR>
 264                                                                 <TD VALIGN="top"><SPAN CLASS="date">13-05-2010</SPAN></TD>
 265                                                                 <TD VALIGN="top">
 266                                                                 Fixed handling of <Q>\*(Ba</Q> escape.  Backed out <SPAN
 267                                                                 CLASS="flag">-fno-ign-chars</SPAN> (pointless complexity).  Fixed erroneous
 268                                                                 breaking of literal lines.  Fixed SYNOPSIS breaking lines before non-initial
 269                                                                 macros.  Changed default section ordering.  Most importantly, the framework for
 270                                                                 end-of-sentence double-spacing is in place, now implemented for the
 271                                                                 <Q>end-of-sentence, end-of-line</Q> rule.  This is a stable roll-back point
 272                                                                 before the mandoc hackathon in Rostock!
 273                                                                 Version: <SPAN CLASS="rev">1.9.25</SPAN>.
 274                                                         </TR>
 275                                                         <TR>
 276                                                                 <TD VALIGN="top"><SPAN CLASS="date">09-05-2010</SPAN></TD>
 277                                                                 <TD VALIGN="top">
 278                                                                 Rolled back break-at-hyphen.  <SPAN CLASS="flag">-DUGLY</SPAN> is now the
 279                                                                 default (no feature splits!).  Free-form text is not de-chunked any more: lines
 280                                                                 are passed whole-sale into the front-end, including whitespace.  Added mailing
 281                                                                 lists.  Lastly, <SPAN CLASS="nm">mdocml</SPAN> is the focus of two <A
 282                                                                 CLASS="external" HREF="http://socghop.appspot.com/">Google Summer of Code</A>
 283                                                                 projects this year: <Q><A CLASS="external"
 284                                                                 HREF="http://netbsd-soc.sourceforge.net/projects/mandoc_ps/">mandoc -Tps</A></Q>
 285                                                                 (NetBSD) and <Q><A CLASS="external"
 286                                                                 HREF="http://wiki.freebsd.org/SummerOfCode2010Projects">BSD-licensed
 287                                                                 Text-Processing Tools</A></Q> (FreeBSD).
 288                                                                 Version: <SPAN CLASS="rev">1.9.24</SPAN>.
 289                                                                 </TD>
 290                                                         </TR>
 291
 292                                                         <TR>
 293                                                                 <TD VALIGN="top"><SPAN CLASS="date">07-04-2010</SPAN></TD>
 294                                                                 <TD VALIGN="top">
 295                                                                 <SPAN CLASS="nm">mdocml</SPAN> has been linked to the <A CLASS="external"
 296                                                                 HREF="http://www.openbsd.org/faq/current.html#20100403">OpenBSD build</a>.  This
 297                                                                 version incorporates many small changes, mostly from patches by OpenBSD,
 298                                                                 allowing crufty manuals to slip by with warnings instead of erroring-out.  Some
 299                                                                 subtle semantic issues, such as punctuation scope, have also been fixed.
 300                                                                 Lastly, some issues with <SPAN CLASS="flag">-Thtml</SPAN> have been fixed, which
 301                                                                 prompted an update to the <A HREF="mandoc.1.html">online</A> <A
 302                                                                 HREF="mandoc_char.7.html">manual</A> <A HREF="man.7.html">pages</A> style
 303                                                                 layout.  Version: <SPAN CLASS="rev">1.9.23</SPAN>.
 304                                                                 </TD>
 305                                                         </TR>
 306                                                         <TR>
 307                                                                 <TD VALIGN="top"><SPAN CLASS="date">31-03-2010</SPAN></TD>
 308                                                                 <TD VALIGN="top">
 309                                                                 Version <SPAN CLASS="rev">1.9.22</SPAN>: adjusted merge of the significant work
 310                                                                 by Ingo Schwarze in getting <Q>Xo</Q> blocks (block full implicit, e.g.,
 311                                                                 <Q>It</Q> for non-columnar lists) to work properly.  This isn't enabled by
 312                                                                 default: you must specify <SPAN CLASS="flag">-DUGLY</SPAN> as a compiler flag
 313                                                                 (see the Makefile for details).
 314                                                                 </TD>
 315                                                         </TR>
 316                                                         <TR>
 317                                                                 <TD VALIGN="top"><SPAN CLASS="date">30-03-2010</SPAN></TD>
 318                                                                 <TD VALIGN="top">
 319                                                                 Version <SPAN CLASS="rev">1.9.20</SPAN>: more efforts to get roff instructions
 320                                                                 in -man documents under control.  Note that roff instructions embedded in
 321                                                                 line-scoped, next-line macros (e.g. <Q>B</Q>) are not supported.  Leading
 322                                                                 punctuation for -mdoc macros, such as <Q>Fl ( ( a</Q>, are now correctly
 323                                                                 handled.
 324                                                                 </TD>
 325                                                         </TR>
 326                                                         <TR>
 327                                                                 <TD VALIGN="top"><SPAN CLASS="date">27-03-2010</SPAN></TD>
 328                                                                 <TD VALIGN="top">
 329                                                                 Version <SPAN CLASS="rev">1.9.18</SPAN>: many fixes (largely pertaining to
 330                                                                 scope) and improvements (e.g., handling of apostrophe-control macros, which
 331                                                                 fixes the strange <Q>BR</Q> seen in some macro output) to handling roff
 332                                                                 instructions in -man documents.
 333                                                                 </TD>
 334                                                         </TR>
 335                                                         <TR>
 336                                                                 <TD VALIGN="top"><SPAN CLASS="date">25-03-2010</SPAN></TD>
 337                                                                 <TD VALIGN="top">
 338                                                                 Version <SPAN CLASS="rev">1.9.17</SPAN> highlights: accept <A
 339                                                                 HREF="http://perldoc.perl.org/" CLASS="external">perlpod</A> standard preamble.
 340                                                                 Also accept (and discard) <Q>de</Q>, <Q>dei</Q>, <Q>am</Q>, <Q>ami</Q>, and
 341                                                                 <Q>ig</Q> roff macro blocks.
 342                                                                 </TD>
 343                                                         </TR>
 344                                                         <TR>
 345                                                                 <TD VALIGN="top"><SPAN CLASS="date">22-03-2010</SPAN></TD>
 346                                                                 <TD VALIGN="top">
 347                                                                 Version <SPAN CLASS="rev">1.9.16</SPAN> highlights: inspired by patches and bug
 348                                                                 reports by Ingo Schwarze, allowed <SPAN CLASS="flag">-man</SPAN> to accept
 349                                                                 non-printing elements to be nested within next-line scopes, such as <Q>br</Q>
 350                                                                 within <Q>B</Q> or <Q>TH</Q>, which is valid roff.  Longsoon architecture also
 351                                                                 noted and Makefile cleaned up.
 352                                                                 </TD>
 353                                                         </TR>
 354                                                         <TR>
 355                                                                 <TD VALIGN="top"><SPAN CLASS="date">18-02-2010</SPAN></TD>
 356                                                                 <TD VALIGN="top">
 357                                                                 Moved to our new <A HREF="http://bsd.lv" CLASS="external">BSD.lv</A> home.
 358                                                                 Version <SPAN CLASS="rev">1.9.15</SPAN> highlights: XHTML is now an acceptable
 359                                                                 output mode for <A HREF="mandoc.1.html">mandoc(1)</A>;  <Q>Xr</Q> made more
 360                                                                 compatible with groff; <Q>Vt</Q> fixed when invoked in SYNOPSIS;  <Q>\\</Q>
 361                                                                 escape removed; end-of-line white-space detected for all lines;  subtle bug
 362                                                                 fixed in list display for some modes;  compatibility layer checked in for
 363                                                                 compilation in diverse UNIX systems;  and column lengths handled correctly.
 364                                                                 </TD>
 365                                                         </TR>
 366                                                 </TBODY>
 367                                         </TABLE>
 368                                 </TD>
 369                         </TR>
 370                         <TR>
 371                                 <TD>
 372                                         <DIV CLASS="foot">
 373                                                 Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2010/05/17 23:50:05 $
 374                                         </DIV>
 375                                 </TD>
 376                         </TR>
 377                 </TBODY>
 378         </TABLE>
 379         </BODY>
 380 </HTML>