contrib/mdocml/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                                         <A NAME="description">DESCRIPTION</A>
  24                                         </H1>
  25
  26                                         <P>
  27                                         <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <Q>-<A HREF="mdoc.7.html">mdoc</A></Q>, the
  28                                         roff macro package of choice for BSD manual pages, and <Q>-<A HREF="man.7.html">man</A></Q>, the
  29                                         predominant historical package for UNIX manuals.  The mission of <SPAN CLASS="nm">mdocml</SPAN> is to
  30                                         deprecate <A HREF="http://www.gnu.org/software/groff/" CLASS="external">groff</A>, the GNU troff
  31                                         implementation, for 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, <A CLASS="external"
  38                                         HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
  39                                         </P>
  40
  41                                         <P>
  42                                         <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mdoc.3.html">libmdoc</A>, <A
  43                                         HREF="man.3.html">libman</A>, and <A HREF="roff.3.html">libroff</A> validating compilers; and <A
  44                                         HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler libraries to format output for UNIX
  45                                         terminals, XHTML, HTML, PostScript, and PDF.  It is a <A CLASS="external"
  46                                         HREF="http://bsd.lv/">BSD.lv</A> project.
  47                                         </P>
  48
  49                                         <P>
  50                                         <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary,
  51                                         <Q>mandoc</Q>.
  52                                         </P>
  53                                 </TD>
  54                         </TR>
  55                         <TR>
  56                                 <TD>
  57                                         <H1>
  58                                         <A NAME="sources">SOURCES</A>
  59                                         </H1>
  60
  61                                         <P>
  62                                         <SPAN CLASS="nm">mdocml</SPAN> is architecture- and system-neutral, written in plain-old C.  The most
  63                                         current version is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>.  A full
  64                                         <A HREF="ChangeLog.html">ChangeLog</A> (<A HREF="ChangeLog.txt">txt</A>) is written with each release.
  65                                         </P>
  66
  67                                         <H2>
  68                                         Current
  69                                         </H2>
  70
  71                                         <TABLE WIDTH="100%" SUMMARY="Current Sources">
  72                                         <COL WIDTH="175">
  73                                         <COL>
  74                                         <TBODY>
  75                                                 <TR>
  76                                                         <TD>Source archive</TD>
  77                                                         <TD>
  78                                                         <A HREF="/snapshots/mdocml.tar.gz">/snapshots/mdocml.tar.gz</A>
  79                                                         (<A HREF="/snapshots/mdocml.md5">md5</A>)
  80                                                         </TD>
  81                                                 </TR>
  82                                                 <TR>
  83                                                         <TD>Online source</TD>
  84                                                         <TD>
  85                                                         <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
  86                                                         </TD>
  87                                                 </TR>
  88                                         </TBODY>
  89                                         </TABLE>
  90
  91                                         <H2>
  92                                         Downstream
  93                                         </H2>
  94
  95                                         <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
  96                                         <COL WIDTH="175">
  97                                         <COL>
  98                                         <TBODY>
  99                                                 <TR>
 100                                                         <TD>DragonFly BSD</TD>
 101                                                         <TD>
 102                                                         <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
 103                                                                 CLASS="external">usr.bin/mandoc</A>
 104                                                         </TD>
 105                                                 </TR>
 106                                                 <TR>
 107                                                         <TD>FreeBSD</TD>
 108                                                         <TD>
 109                                                         <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
 110                                                                 CLASS="external">ports/textproc/mdocml</A>
 111                                                         </TD>
 112                                                 </TR>
 113                                                 <TR>
 114                                                         <TD>NetBSD</TD>
 115                                                         <TD>
 116                                                         <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
 117                                                                 CLASS="external">src/external/bsd/mdocml</A>
 118                                                         </TD>
 119                                                 </TR>
 120                                                 <TR>
 121                                                         <TD>OpenBSD</TD>
 122                                                         <TD>
 123                                                         <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
 124                                                                 CLASS="external">src/usr.bin/mandoc</A>
 125                                                         </TD>
 126                                                 </TR>
 127                                         </TBODY>
 128                                         </TABLE>
 129
 130                                         <H2>
 131                                         Historical
 132                                         </H2>
 133
 134                                         <TABLE WIDTH="100%" SUMMARY="Archived Sources">
 135                                         <COL WIDTH="175">
 136                                         <COL>
 137                                         <TBODY>
 138                                                 <TR>
 139                                                         <TD>Source archive</TD>
 140                                                         <TD>
 141                                                         <A HREF="/snapshots/">/snapshots/</A>
 142                                                         </TD>
 143                                                 </TR>
 144                                         </TBODY>
 145                                         </TABLE>
 146                                 </TD>
 147                         </TR>
 148                         <TR>
 149                                 <TD>
 150                                         <H1>
 151                                         <A NAME="documentation">DOCUMENTATION</A>
 152                                         </H1>
 153
 154                                         <P>
 155                                                 These manuals are generated automatically and refer to the current snapshot.
 156                                         </P>
 157
 158                                         <TABLE WIDTH="100%" SUMMARY="Documentation">
 159                                         <COL WIDTH="175">
 160                                         <COL>
 161                                         <TBODY>
 162                                                 <TR>
 163                                                         <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
 164                                                         <TD VALIGN="top">
 165                                                                 format and display UNIX manuals
 166                                                                 <SPAN STYLE="font-size: smaller;">
 167                                                                         (<A HREF="mandoc.1.txt">text</A> |
 168                                                                         <A HREF="mandoc.1.xhtml">xhtml</A> |
 169                                                                         <A HREF="mandoc.1.pdf">pdf</A> |
 170                                                                         <A HREF="mandoc.1.ps">postscript</A>)
 171                                                                 </SPAN>
 172                                                         </TD>
 173                                                 </TR>
 174                                                 <TR>
 175                                                         <TD VALIGN="top"><A HREF="man.3.html">man(3)</A></TD>
 176                                                         <TD VALIGN="top">
 177                                                                 man macro compiler library
 178                                                                 <SPAN STYLE="font-size: smaller;">
 179                                                                         (<A HREF="man.3.txt">text</A> |
 180                                                                         <A HREF="man.3.xhtml">xhtml</A> |
 181                                                                         <A HREF="man.3.pdf">pdf</A> |
 182                                                                         <A HREF="man.3.ps">postscript</A>)
 183                                                                 </SPAN>
 184                                                         </TD>
 185                                                 </TR>
 186                                                 <TR>
 187                                                         <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
 188                                                         <TD VALIGN="top">
 189                                                                 mdoc macro compiler library
 190                                                                 <SPAN STYLE="font-size: smaller;">
 191                                                                         (<A HREF="mdoc.3.txt">text</A> |
 192                                                                         <A HREF="mdoc.3.xhtml">xhtml</A> |
 193                                                                         <A HREF="mdoc.3.pdf">pdf</A> |
 194                                                                         <A HREF="mdoc.3.ps">postscript</A>)
 195                                                                 </SPAN>
 196                                                         </TD>
 197                                                 </TR>
 198                                                 <TR>
 199                                                         <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
 200                                                         <TD VALIGN="top">
 201                                                                 roff macro compiler library
 202                                                                 <SPAN STYLE="font-size: smaller;">
 203                                                                         (<A HREF="roff.3.txt">text</A> |
 204                                                                         <A HREF="roff.3.xhtml">xhtml</A> |
 205                                                                         <A HREF="roff.3.pdf">pdf</A> |
 206                                                                         <A HREF="roff.3.ps">postscript</A>)
 207                                                                 </SPAN>
 208                                                         </TD>
 209                                                 </TR>
 210                                                 <TR>
 211                                                         <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
 212                                                         <TD VALIGN="top">
 213                                                                 man language reference
 214                                                                 <SPAN STYLE="font-size: smaller;">
 215                                                                         (<A HREF="man.7.txt">text</A> |
 216                                                                         <A HREF="man.7.xhtml">xhtml</A> |
 217                                                                         <A HREF="man.7.pdf">pdf</A> |
 218                                                                         <A HREF="man.7.ps">postscript</A>)
 219                                                                 </SPAN>
 220                                                         </TD>
 221                                                 </TR>
 222                                                 <TR>
 223                                                         <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
 224                                                         <TD VALIGN="top">
 225                                                                 mandoc special characters
 226                                                                 <SPAN STYLE="font-size: smaller;">
 227                                                                         (<A HREF="mandoc_char.7.txt">text</A> |
 228                                                                         <A HREF="mandoc_char.7.xhtml">xhtml</A> |
 229                                                                         <A HREF="mandoc_char.7.pdf">pdf</A> |
 230                                                                         <A HREF="mandoc_char.7.ps">postscript</A>)
 231                                                                 </SPAN>
 232                                                         </TD>
 233                                                 </TR>
 234                                                 <TR>
 235                                                         <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
 236                                                         <TD VALIGN="top">
 237                                                                 mdoc language reference
 238                                                                 <SPAN STYLE="font-size: smaller;">
 239                                                                         (<A HREF="mdoc.7.txt">text</A> |
 240                                                                         <A HREF="mdoc.7.xhtml">xhtml</A> |
 241                                                                         <A HREF="mdoc.7.pdf">pdf</A> |
 242                                                                         <A HREF="mdoc.7.ps">postscript</A>)
 243                                                                 </SPAN>
 244                                                         </TD>
 245                                                 </TR>
 246                                                 <TR>
 247                                                         <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
 248                                                         <TD VALIGN="top">
 249                                                                 roff-mandoc language reference
 250                                                                 <SPAN STYLE="font-size: smaller;">
 251                                                                         (<A HREF="roff.7.txt">text</A> |
 252                                                                         <A HREF="roff.7.xhtml">xhtml</A> |
 253                                                                         <A HREF="roff.7.pdf">pdf</A> |
 254                                                                         <A HREF="roff.7.ps">postscript</A>)
 255                                                                 </SPAN>
 256                                                         </TD>
 257                                                 </TR>
 258                                                 <TR>
 259                                                         <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
 260                                                         <TD VALIGN="top">
 261                                                                 tbl-mandoc language reference
 262                                                                 <SPAN STYLE="font-size: smaller;">
 263                                                                         (<A HREF="tbl.7.txt">text</A> |
 264                                                                         <A HREF="tbl.7.xhtml">xhtml</A> |
 265                                                                         <A HREF="tbl.7.pdf">pdf</A> |
 266                                                                         <A HREF="tbl.7.ps">postscript</A>)
 267                                                                 </SPAN>
 268                                                         </TD>
 269                                                 </TR>
 270                                         </TBODY>
 271                                         </TABLE>
 272
 273                                         <P>
 274                                         See <Q><A CLASS="external" HREF="http://manpages.bsd.lv">Writing UNIX Manual Pages</A></Q> for a general
 275                                         introduction to manpages and mdoc.
 276                                         </P>
 277                                 </TD>
 278                         </TR>
 279                         <TR>
 280                                 <TD>
 281                                         <H1>
 282                                         <A NAME="contact">CONTACT</A>
 283                                         </H1>
 284
 285                                         <P>
 286                                                 Please use the mailing lists for bug-reports, patches, questions, etc. (these require
 287                                                 subscription).  Beyond that, contact Kristaps at <A
 288                                                 HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q=="
 289                                                 TITLE="Reveal this e-mail address">kris...</A>@bsd.lv.
 290                                         </P>
 291
 292                                         <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
 293                                                 <COL WIDTH="175">
 294                                                 <COL>
 295                                                 <TBODY>
 296                                                         <TR>
 297                                                                 <TD>
 298                                                                         disc<A CLASS="external" TITLE="Reveal this e-mail address"
 299                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
 300                                                                 </TD>
 301                                                                 <TD>
 302                                                                         bug-reports, general questions, and announcements
 303                                                                         <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/discuss/summary.html">archive</A>)</SPAN>
 304                                                                 </TD>
 305                                                         </TR>
 306                                                         <TR>
 307                                                                 <TD>
 308                                                                         tec<A CLASS="external" TITLE="Reveal this e-mail address"
 309                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&amp;c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
 310                                                                 </TD>
 311                                                                 <TD>
 312                                                                         patches and system discussions
 313                                                                         <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/tech/summary.html">archive</A>)</SPAN>
 314                                                                 </TD>
 315                                                         </TR>
 316                                                         <TR>
 317                                                                 <TD>
 318                                                                         sou<A CLASS="external" TITLE="Reveal this e-mail address"
 319                                                                         HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
 320                                                                 </TD>
 321                                                                 <TD>
 322                                                                         source commit messages
 323                                                                         <SPAN STYLE="font-size: smaller;">(<A HREF="/archives/source/summary.html">archive</A>)</SPAN>
 324                                                                 </TD>
 325                                                         </TR>
 326                                                 </TBODY>
 327                                         </TABLE>
 328                                 </TD>
 329                         </TR>
 330                         <TR>
 331                                 <TD>
 332                                         <H1>
 333                                         <A NAME="news">NEWS</A>
 334                                         </H1>
 335                                         <DIV CLASS="news">
 336                                                 <P>
 337                                                         <SPAN CLASS="date">07-01-2011</SPAN>:
 338                                                         version 1.10.9
 339                                                 </P>
 340                                                 <P>
 341                                                         Many back-end fixes have been implemented: argument handling (quoting), <A
 342                                                         HREF="man.7.html">man</A> improvements, error/warning classes, and many more.
 343                                                 </P>
 344                                                 <P>
 345                                                         Initial <A HREF="tbl.7.html">tbl</A> functionality (see the <Q>TS</Q>, <Q>TE</Q>, and
 346                                                         <Q>T&amp;</Q> macros in the <A HREF="roff.7.html#x5c265453">roff</A> manual) has been
 347                                                         merged from <A CLASS="external" HREF="http://tbl.bsd.lv">tbl.bsd.lv</A>.  Output is
 348                                                         still minimal, especially for <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
 349                                                         CLASS="flag">-Txhtml</SPAN>, but manages to at least display data.  This means that <A
 350                                                         HREF="mandoc.1.html">mandoc</A> now has built-in support for two troff preprocessors via
 351                                                         <A HREF="roff.3.html">libroff</A>: soelim and tbl.
 352                                                 </P>
 353                                         </DIV>
 354                                         <DIV CLASS="news">
 355                                                 <P>
 356                                                         <SPAN CLASS="date">24-12-2010</SPAN>:
 357                                                         version 1.10.8
 358                                                 </P>
 359                                                 <P>
 360                                                         Significant improvements merged from <A CLASS="external"
 361                                                         HREF="http://www.openbsd.org">OpenBSD</A> downstream, including
 362                                                 </P>
 363                                                 <UL>
 364                                                         <LI>many new <A HREF="roff.7.html">roff</A> components,</LI>
 365                                                         <LI>in-line implementation of troff's soelim,</LI>
 366                                                         <LI>broken-block handling,</LI>
 367                                                         <LI>overhauled error classifications, and</LI>
 368                                                         <LI>cleaned up handling of error conditions.</LI>
 369                                                 </UL>
 370                                                 <P>
 371                                                         Also overhauled the <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
 372                                                         CLASS="flag">-Txhtml</SPAN> output modes.  They now display readable output in arbitrary
 373                                                         browsers, including text-based ones like <A CLASS="external"
 374                                                         HREF="http://lynx.isc.org">lynx</A>.  See HTML and XHTML manuals in the <A
 375                                                         HREF="#documentation">DOCUMENTATION</A> section for examples.  <SPAN
 376                                                         CLASS="attn">Attention: available style-sheet classes have been considerably
 377                                                         changed!</SPAN> See the <SPAN CLASS="file">example.style.css</SPAN> file for details.
 378                                                         Lastly, <A HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> have been
 379                                                         cleaned up and reduced in size and complexity.
 380                                                 </P>
 381                                         </DIV>
 382                                         <P>
 383                                                 See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
 384                                                 historical notes.
 385                                         </P>
 386                                 </TD>
 387                         </TR>
 388                         <TR>
 389                                 <TD>
 390                                         <DIV CLASS="foot">
 391                                                 Copyright &#169; 2008&#8211;2010 Kristaps Dzonsons, $Date: 2011/01/07 13:10:03 $
 392                                         </DIV>
 393                                 </TD>
 394                         </TR>
 395                 </TBODY>
 396         </TABLE>
 397         </BODY>
 398 </HTML>