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                 <LINK REL="stylesheet" HREF="index.css" TYPE="text/css" MEDIA="all">
   6                 <TITLE>mdocml | mdoc macro compiler</TITLE>
   7         </HEAD>
   8         <BODY>
   9                 <P CLASS="head">
  10                         <B>mdocml</B> &#8211; mdoc macro compiler, current version @VERSION@ (@VDATE@)
  11                 </P>
  12                 <P CLASS="subhead">
  13                         Sources: <A HREF="/snapshots/mdocml.tar.gz">current</A>,
  14                         <A HREF="/cgi-bin/cvsweb/?cvsroot=mdocml">cvsweb</A>
  15                         (<A HREF="/snapshots/">archives</A>)
  16                         |
  17                         Binaries: <A
  18                         HREF="/binaries/mdocml-win32.zip">windows 32-bit</A>, <A
  19                         HREF="/binaries/mdocml-win64.zip">windows 64-bit</A>, <A
  20                         HREF="/binaries/mdocml-macosx.zip">mac os x</A>
  21                         (<A HREF="/binaries/">archives</A>)
  22                 </P>
  23                 <H1>
  24                         <A NAME="description">Description</A>
  25                 </H1>
  26                 <P>
  27                         <SPAN CLASS="nm">mdocml</SPAN> is a suite of tools compiling <I><A HREF="mdoc.7.html">mdoc</A></I>, the roff macro
  28                         package of choice for BSD manual pages, and <I><A HREF="man.7.html">man</A></I>, the predominant historical package for
  29                         UNIX 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 troff implementation, for displaying <I>mdoc</I>
  31                         pages whilst providing token support for <I>man</I>.
  32                 </P>
  33                 <P>
  34                         Why?  groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL.  It runs slowly, produces
  35                         uncertain output, and varies in operation from system to system.  mdocml strives to fix this (respectively small, C, <A
  36                         CLASS="external" HREF="http://www.isc.org/software/license">ISC</A>-licensed, fast and regular).
  37                 </P>
  38                 <P>
  39                         <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating compiler and <A
  40                         HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format output for UNIX terminals (with
  41                         support for wide-character locales), XHTML, HTML, PostScript, and PDF.
  42                         It also includes <A HREF="preconv.1.html">preconv</A>, for recoding multibyte manuals;
  43                         <A HREF="demandoc.1.html">demandoc</A>, for emitting only text parts of manuals;
  44                         and <A HREF="mandocdb.8.html">mandocdb</A>, for indexing manuals.
  45                         It is a <A CLASS="external" HREF="http://bsd.lv/">BSD.lv</A> project.
  46                 </P>
  47                 <P>
  48                         <I>Disambiguation</I>: <SPAN CLASS="nm">mdocml</SPAN> is often referred to by its installed binary, <Q>mandoc</Q>.
  49                 </P>
  50                 <H2>
  51                         <A NAME="sources">Sources</A>
  52                 </H2>
  53                 <P>
  54                         <SPAN CLASS="nm">mdocml</SPAN> is in plain-old ANSI C and should build and run on any modern system.
  55                         To build and install into <I>/usr/local/</I>, just run <CODE>make install</CODE>.
  56                         Be aware: if you have an existing groff installation, this may overwrite its <B>preconv</B> binary.
  57                         The <A HREF="mandocdb.8.html">mandocdb</A> utility is not yet linked to the build; please <A HREF="#contact">contact
  58                         us</A> if you plan to use it.
  59                 </P>
  60                 <H2>
  61                         <A NAME="binaries">Binaries</A>
  62                 </H2>
  63                 <P>
  64                         Binary archives consist of pre-compiled binaries, manuals, and other necessary files.
  65                         Universal (Mac OS X) binaries are compiled for the PCC, i386, and x86_64 architectures.
  66                         Windows binaries are compiled with <A CLASS="external" HREF="http://www.mingw.org">MingW</A> for the 32-bit (i686) and
  67                         64-bit (x86_64) architectures.
  68                 </P>
  69                 <H2>
  70                         Downstream
  71                 </H2>
  72                 <P>
  73                         Several systems come bundled with <SPAN CLASS="nm">mdocml</SPAN> utilities.
  74                         If your system does not appear below, the maintainers have not contacted me and it should not be considered
  75                         <Q>official</Q>.
  76                         Please <A HREF="#contact">contact us</A> if you plan on maintaining a downstream version!
  77                 </P>
  78                 <TABLE WIDTH="100%" SUMMARY="Downstream Sources">
  79                         <COL WIDTH="175">
  80                         <COL>
  81                         <TBODY>
  82                                 <TR>
  83                                         <TD>DragonFly BSD</TD>
  84                                         <TD>
  85                                         <A HREF="http://gitweb.dragonflybsd.org/dragonfly.git/tree/HEAD:/usr.bin/mandoc"
  86                                                 CLASS="external">usr.bin/mandoc</A>
  87                                         </TD>
  88                                 </TR>
  89                                 <TR>
  90                                         <TD>FreeBSD</TD>
  91                                         <TD>
  92                                         <A HREF="http://www.freebsd.org/cgi/cvsweb.cgi/ports/textproc/mdocml/"
  93                                                 CLASS="external">ports/textproc/mdocml</A>
  94                                         </TD>
  95                                 </TR>
  96                                 <TR>
  97                                         <TD>NetBSD</TD>
  98                                         <TD>
  99                                         <A HREF="http://cvsweb.netbsd.org/bsdweb.cgi/src/external/bsd/mdocml/"
 100                                                 CLASS="external">src/external/bsd/mdocml</A>
 101                                         </TD>
 102                                 </TR>
 103                                 <TR>
 104                                         <TD>OpenBSD</TD>
 105                                         <TD>
 106                                         <A HREF="http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/mandoc/"
 107                                                 CLASS="external">src/usr.bin/mandoc</A>
 108                                         </TD>
 109                                 </TR>
 110                         </TBODY>
 111                 </TABLE>
 112                 <H1>
 113                         <A NAME="documentation">Documentation</A>
 114                 </H1>
 115                 <P>
 116                         These manuals are generated automatically and refer to the current release.
 117                         They are the authoritative documentation for the <SPAN CLASS="nm">mdocml</SPAN> system.
 118                 </P>
 119
 120                 <TABLE WIDTH="100%" SUMMARY="Documentation">
 121                         <COL WIDTH="175">
 122                         <COL>
 123                         <TBODY>
 124                                 <TR>
 125                                         <TD VALIGN="top"><A HREF="mandoc.1.html">mandoc(1)</A></TD>
 126                                         <TD VALIGN="top">
 127                                                 format and display UNIX manuals
 128                                                         (<A HREF="mandoc.1.txt">text</A> |
 129                                                         <A HREF="mandoc.1.xhtml">xhtml</A> |
 130                                                         <A HREF="mandoc.1.pdf">pdf</A> |
 131                                                         <A HREF="mandoc.1.ps">ps</A>)
 132                                         </TD>
 133                                 </TR>
 134                                 <TR>
 135                                         <TD VALIGN="top"><A HREF="demandoc.1.html">demandoc(1)</A></TD>
 136                                         <TD VALIGN="top">
 137                                                 emit only text of UNIX manuals
 138                                                         (<A HREF="demandoc.1.txt">text</A> |
 139                                                         <A HREF="demandoc.1.xhtml">xhtml</A> |
 140                                                         <A HREF="demandoc.1.pdf">pdf</A> |
 141                                                         <A HREF="demandoc.1.ps">ps</A>)
 142                                         </TD>
 143                                 </TR>
 144                                 <TR>
 145                                         <TD VALIGN="top"><A HREF="preconv.1.html">preconv(1)</A></TD>
 146                                         <TD VALIGN="top">
 147                                                 recode multibyte UNIX manuals
 148                                                         (<A HREF="preconv.1.txt">text</A> |
 149                                                         <A HREF="preconv.1.xhtml">xhtml</A> |
 150                                                         <A HREF="preconv.1.pdf">pdf</A> |
 151                                                         <A HREF="preconv.1.ps">ps</A>)
 152                                         </TD>
 153                                 </TR>
 154                                 <TR>
 155                                         <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
 156                                         <TD VALIGN="top">
 157                                                 mandoc macro compiler library
 158                                                         (<A HREF="mandoc.3.txt">text</A> |
 159                                                         <A HREF="mandoc.3.xhtml">xhtml</A> |
 160                                                         <A HREF="mandoc.3.pdf">pdf</A> |
 161                                                         <A HREF="mandoc.3.ps">ps</A>)
 162                                         </TD>
 163                                 </TR>
 164                                 <TR>
 165                                         <TD VALIGN="top"><A HREF="man.7.html">man(7)</A></TD>
 166                                         <TD VALIGN="top">
 167                                                 man language reference
 168                                                         (<A HREF="man.7.txt">text</A> |
 169                                                         <A HREF="man.7.xhtml">xhtml</A> |
 170                                                         <A HREF="man.7.pdf">pdf</A> |
 171                                                         <A HREF="man.7.ps">ps</A>)
 172                                         </TD>
 173                                 </TR>
 174                                 <TR>
 175                                         <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
 176                                         <TD VALIGN="top">
 177                                                 eqn-mandoc language reference
 178                                                         (<A HREF="eqn.7.txt">text</A> |
 179                                                         <A HREF="eqn.7.xhtml">xhtml</A> |
 180                                                         <A HREF="eqn.7.pdf">pdf</A> |
 181                                                         <A HREF="eqn.7.ps">ps</A>)
 182                                         </TD>
 183                                 </TR>
 184                                 <TR>
 185                                         <TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
 186                                         <TD VALIGN="top">
 187                                                 mandoc special characters
 188                                                         (<A HREF="mandoc_char.7.txt">text</A> |
 189                                                         <A HREF="mandoc_char.7.xhtml">xhtml</A> |
 190                                                         <A HREF="mandoc_char.7.pdf">pdf</A> |
 191                                                         <A HREF="mandoc_char.7.ps">ps</A>)
 192                                         </TD>
 193                                 </TR>
 194                                 <TR>
 195                                         <TD VALIGN="top"><A HREF="mdoc.7.html">mdoc(7)</A></TD>
 196                                         <TD VALIGN="top">
 197                                                 mdoc language reference
 198                                                         (<A HREF="mdoc.7.txt">text</A> |
 199                                                         <A HREF="mdoc.7.xhtml">xhtml</A> |
 200                                                         <A HREF="mdoc.7.pdf">pdf</A> |
 201                                                         <A HREF="mdoc.7.ps">ps</A>)
 202                                         </TD>
 203                                 </TR>
 204                                 <TR>
 205                                         <TD VALIGN="top"><A HREF="roff.7.html">roff(7)</A></TD>
 206                                         <TD VALIGN="top">
 207                                                 roff-mandoc language reference
 208                                                         (<A HREF="roff.7.txt">text</A> |
 209                                                         <A HREF="roff.7.xhtml">xhtml</A> |
 210                                                         <A HREF="roff.7.pdf">pdf</A> |
 211                                                         <A HREF="roff.7.ps">ps</A>)
 212                                         </TD>
 213                                 </TR>
 214                                 <TR>
 215                                         <TD VALIGN="top"><A HREF="tbl.7.html">tbl(7)</A></TD>
 216                                         <TD VALIGN="top">
 217                                                 tbl-mandoc language reference
 218                                                         (<A HREF="tbl.7.txt">text</A> |
 219                                                         <A HREF="tbl.7.xhtml">xhtml</A> |
 220                                                         <A HREF="tbl.7.pdf">pdf</A> |
 221                                                         <A HREF="tbl.7.ps">ps</A>)
 222                                         </TD>
 223                                 </TR>
 224                                 <TR>
 225                                         <TD VALIGN="top"><A HREF="mandocdb.8.html">mandocdb(8)</A></TD>
 226                                         <TD VALIGN="top">
 227                                                 index UNIX manuals
 228                                                         (<A HREF="mandocdb.8.txt">text</A> |
 229                                                         <A HREF="mandocdb.8.xhtml">xhtml</A> |
 230                                                         <A HREF="mandocdb.8.pdf">pdf</A> |
 231                                                         <A HREF="mandocdb.8.ps">ps</A>)
 232                                         </TD>
 233                                 </TR>
 234                         </TBODY>
 235                 </TABLE>
 236                 <H1>
 237                         <A NAME="contact">Contact</A>
 238                 </H1>
 239                 <P>
 240                         Use the mailing lists for bug-reports, patches, questions, etc.  Please check the
 241                         <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml">TODO</A> for known issues
 242                         before posting.  All lists are subscription-only: send a blank e-mail to the listed address to subscribe.  Beyond that,
 243                         contact Kristaps at <A HREF="http://mailhide.recaptcha.net/d?k=01M6h_w7twDp58ZgH57eWC_w==&amp;c=Q2DBUt401ePlSeupJFrq_Q==" TITLE="Reveal
 244                         this e-mail address">kris...</A>@bsd.lv.
 245                 </P>
 246                 <TABLE WIDTH="100%" SUMMARY="Mailing Lists">
 247                         <COL WIDTH="175">
 248                         <COL>
 249                         <TBODY>
 250                                 <TR>
 251                                         <TD>
 252                                                 disc<A CLASS="external" TITLE="Reveal this e-mail address"
 253                                                 HREF="http://www.google.com/recaptcha/mailhide/d?k=01KQ80PFH5n3BBNpF5Gs4sRg==&amp;c=EV1QytpQqTHSItc2IXvZyocgYLPnG5K0JKw_gwMC9yc=">...</A>@mdocml.bsd.lv
 254                                         </TD>
 255                                         <TD>
 256                                                 bug-reports, general questions, and announcements
 257                                                 (<A HREF="/archives/discuss/">archive</A>)
 258                                         </TD>
 259                                 </TR>
 260                                 <TR>
 261                                         <TD>
 262                                                 tec<A CLASS="external" TITLE="Reveal this e-mail address"
 263                                                 HREF="http://www.google.com/recaptcha/mailhide/d?k=01qDX_iV0RlUOarEvb6mR28g==&amp;c=gRXsTjza0NNCFPaYu-Taj2tF0pmYZSc90EZkFkhkxgo=">...</A>@mdocml.bsd.lv
 264                                         </TD>
 265                                         <TD>
 266                                                 patches and system discussions
 267                                                 (<A HREF="/archives/tech/">archive</A>)
 268                                         </TD>
 269                                 </TR>
 270                                 <TR>
 271                                         <TD>
 272                                                 sou<A CLASS="external" TITLE="Reveal this e-mail address"
 273                                                 HREF="http://www.google.com/recaptcha/mailhide/d?k=01prQrAZhhl2EbIwVcRfABsQ==&amp;c=KtTW4Yic9xk-8g40KzJoca4fR3MYXv28g8NC6OQV-T8=">...</A>@mdocml.bsd.lv
 274                                         </TD>
 275                                         <TD>
 276                                                 source commit messages
 277                                                 (<A HREF="/archives/source/">archive</A>)
 278                                         </TD>
 279                                 </TR>
 280                         </TBODY>
 281                 </TABLE>
 282                 <H1>
 283                         <A NAME="news">News</A>
 284                 </H1>
 285                 <P CLASS="news">
 286                         xx-xx-2011: version 1.11.x
 287                 </P>
 288                 <P>
 289                         For <A HREF="tbl.7.html">tbl</A>, the horizontal spacing of tables was rewritten completely.
 290                         It is now compatible with groff, both with and without frames and rulers.
 291                         Nesting of indented blocks is now supported in <A HREF="man.7.html">man</A>,
 292                         and several bugs were fixed regarding various kinds of indentation and alignment.
 293                         The page headers in <A HREF="mdoc.7.html">mdoc</A> are now nicer even for very long titles.
 294                         Implementation of a mdoc-to-man-coverter (-Tman) was started.
 295                         This is work in progress and will be developed in the tree.
 296                         The <A HREF="mdoc.7.html">mdoc</A> and <A HREF="man.7.html">man</A> manuals have been made more readable
 297                         by adding MACRO OVERVIEW sections, by moving the gory details of the LANGUAGE SYNTAX to the <A HREF="roff.7.html">roff</A> manual,
 298                         and by moving the very technical MACRO SYNTAX sections down to the bottom of the page.
 299                 </P>
 300                 <P CLASS="news">
 301                         02-09-2011: version 1.11.7
 302                 </P>
 303                 <P>
 304                         Added <A HREF="demandoc.1.html">demandoc</A> utility for stripping away macros and escapes.  This replaces the
 305                         historical <CODE>deroff</CODE> utility.  Also improved the <A HREF="mdoc.7.html">mdoc</A> and <A HREF="man.7.html">man</A> manuals.
 306                 </P>
 307                 <P CLASS="news">
 308                         16-08-2011: version 1.11.6
 309                 </P>
 310                 <P>
 311                         Handling of <B>tr</B> macro in <A HREF="roff.7.html">roff</A> implemented.  This makes Perl documentation much more
 312                         readable.  Hyphenation is also now enabled in <A HREF="man.7.html">man</A> format documents.  Many other general
 313                         improvements have been implemented.  Furthermore, a 64-bit Windows binary is now available at <A
 314                         HREF="/binaries/mdocml-win64.zip">mdocml-win64.zip</A> and a Mac OS X universal binary is available at <A
 315                         HREF="/binaries/mdocml-macosx.zip">mdocml-macosx.zip</A>.
 316                 </P>
 317                 <P CLASS="news">
 318                         24-07-2011: version 1.11.5
 319                 </P>
 320                 <P>
 321                         Significant <A HREF="eqn.7.html">eqn</A> improvements.  <SPAN CLASS="nm">mdocml</SPAN> can now parse arbitrary eqn input
 322                         (although few GNU extensions are accepted, nor is mixing low-level roff with eqn).  See the <A HREF="eqn.7.html">eqn</A>
 323                         manual for details.  For the time being, equations are rendered as simple in-line text.  The equation parser satisfies
 324                         the language specified in the <A CLASS="external" HREF="http://www.kohala.com/start/troff/v7man/eqn/eqn2e.ps">Second
 325                         Edition User's Guide</A>.
 326                 </P>
 327                 <P>
 328                         This is also the first release featuring a distributed Windows binary, available at <A
 329                         HREF="/binaries/mdocml-win32.zip">/binaries/mdocml-win32.zip</A>.
 330                 </P>
 331                 <P>
 332                         See <A HREF="http://mdocml.bsd.lv/cgi-bin/cvsweb/index.sgml?cvsroot=mdocml">cvsweb</A> for
 333                         historical notes.
 334                 </P>
 335                 <P CLASS="foot">
 336                         <SMALL>
 337                                 Copyright &#169; 2008&#8211;2011
 338                                 <A CLASS="external" HREF="http://kristaps.bsd.lv">Kristaps Dzonsons</A>,
 339                                 $Date: 2011/09/27 22:59:01 $
 340                         </SMALL>
 341                 </P>
 342         </BODY>
 343 </HTML>