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