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="style.css" type="text/css" media="all">
   7                 <title>mdocml.bsd.lv</title>
   8         </head>
   9         <body>
  10         <table width="600">
  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 &#8220;mdoc&#8221;, the roff macro
  28                                         package for BSD manual pages.  The mission of <span class="nm">mdocml</span> is to deprecate <a
  29                                         href="http://www.gnu.org/software/groff/" class="external">groff</a>, the GNU roff implementation, for
  30                                         displaying BSD mdoc pages.
  31                                         </p>
  32
  33                                         <p>
  34                                         Why?  groff amounts to roughly 5,2 MB of source code (OpenBSD 4.2), some of which is C++ and all of
  35                                         which is GPL.  It runs slowly, produces uncertain output, and varies in operation from system
  36                                         to system.  mdocml strives to fix this (respectively small, C, ISC-licensed, fast and regular).
  37                                         </p>
  38
  39                                         <p>
  40                                         The core of <span class="nm">mdocml</span> is the libmdoc library, a validating scanner-parser producing
  41                                         intermediate-form output from mdoc input.  libmdoc is a simple, fast library operating on memory buffers
  42                                         of mdoc input.  Its intermediate output, an abstract syntax tree, is fully documented in the <span
  43                                         class="man">mdoc(3)</span> reference manual.
  44                                         </p>
  45
  46                                         <p>
  47                                         There are three utilities implementing <span class="man">mdoc(3)</span>:
  48                                         </p>
  49
  50                                         <ul>
  51                                         <li><span class="man">mdocterm(1)</span> &#8211; formats mdoc input for display on the terminal
  52                                         <li><span class="man">mdochtml(1)</span> &#8211; formats mdoc input as HTML/CSS (nascent)
  53                                         <li><span class="man">mdoclint(1)</span> &#8211; validates mdoc input
  54                                         <li><span class="man">mdoctree(1)</span> &#8211; prints input abstract syntax tree
  55                                         </ul>
  56
  57                                         <p>
  58                                         The <span class="man">mdocterm(1)</span> utility is intended to deprecate usage of <a
  59                                         href="http://www.gnu.org/software/groff/" class="external">groff</a> for displaying BSD manuals to the
  60                                         terminal, either directly or cached as a &#8220;catman&#8221; page.
  61                                         </p>
  62
  63                                         <p>
  64                                         <span class="attn">Please submit patches!</span> Although a significant implementation exists, work
  65                                         remains for the backend library and especially the front-end utilities.  See the <a
  66                                         href="#contact">contact</a> information below to submit patches and bug reports.
  67                                         </p>
  68                                 </td>
  69                         </tr>
  70                         <tr>
  71                                 <td>
  72                                         <h1>
  73                                         INSTALLING SOURCES
  74                                         </h1>
  75
  76                                         <p>
  77                                         Sources correctly build and install on OpenBSD, NetBSD and Linux operating systems, tested variously on
  78                                         i386, AMD64 and Alpha.
  79                                         </p>
  80
  81                                         <p>
  82                                         The most current version is <span class="attn">@VERSION@</span>, dated
  83                                         <span class="attn">@VDATE@</span>.
  84                                         </p>
  85
  86                                         <h2>
  87                                         Snapshot source
  88                                         </h2>
  89
  90                                         <p>
  91                                         CVS sources are checkedout and snapshotted with version updates.  These may be found in the <a
  92                                         href="/snapshots/">/snapshots/</a> directory.
  93                                         </p>
  94
  95                                         <p class="boxed">
  96                                         % cd /tmp<br>
  97                                         % ftp -V -o- http://mdocml.bsd.lv/snapshots/mdocml.tar.gz | tar -zvxf -<br>
  98                                         % cd mdocml<br>
  99                                         % make all<br>
 100                                         % make regress<br>
 101                                         # make install
 102                                         </p>
 103
 104                                         <h2>
 105                                         Snapshot port
 106                                         </h2>
 107
 108                                         <p>
 109                                         The source snapshot is automatically converted into an OpenBSD port (ports for other BSD systems not
 110                                         yet available).  These may be found in the <a href="/ports-openbsd/">/ports-openbsd/</a> directory.
 111                                         You <span class="emph">must</span> have the ports tree installed.
 112                                         </p>
 113
 114                                         <p class="boxed">
 115                                         # pkg_delete mdocml<br>
 116                                         # cd /usr/ports/devel/<br>
 117                                         # rm -rf mdocml<br>
 118                                         # ftp -V -o- http://mdocml.bsd.lv/ports-openbsd/mdocml.tar.gz | tar -zvxf -<br>
 119                                         # cd mdocml<br>
 120                                         # make build<br>
 121                                         # make regress<br>
 122                                         # make install
 123                                         </p>
 124                                 </td>
 125                         </tr>
 126                         <tr>
 127                                 <td>
 128                                         <h1>
 129                                         CONTACT
 130                                         </h1>
 131
 132                                         <p>
 133                                         Please contact Kristaps, kris<a class="external"
 134                                         href="http://mailhide.recaptcha.net/d?k=01jt88xIsFONwVjHZmGpc4AQ==&amp;c=sb5E6ulipc-eTnpTVqI-BQ=="
 135                                         onclick="window.open('http://mailhide.recaptcha.net/d?k=01jt88xIsFONwVjHZmGpc4AQ==&amp;c=sb5E6ulipc-eTnpTVqI-BQ==',
 136                                         '', 'toolbar=0,scrollbars=0,location=0,statusbar=0,menubar=0,resizable=0,width=500,height=300'); return
 137                                         false;" title="Reveal this e-mail address">...</a>@kth.se, with questions, bug reports, patches, and so on.
 138                                         </p>
 139
 140                                         <p>
 141                                         If you'd like to submit patches, please contact us beforehand in case larger changes are pending but not
 142                                         checked in.  If making a bug report, please make sure it's repeatable on the most current snapshot.
 143                                         </p>
 144                                 </td>
 145                         </tr>
 146                         <tr>
 147                                 <td>
 148                                         <div class="foot">
 149                                                 Copyright &#169; 2009 Kristaps D&#382;onsons, $Date: 2009/02/27 10:55:16 $
 150                                         </div>
 151                                 </td>
 152                         </tr>
 153                 </tbody>
 154         </table>
 155         </body>
 156 </html>