[Openmcl-devel] ccl manual (was Re: trace on recursive functions)

[R. Matthew Emerson]

On Dec 11, 2009, at 12:07 AM, Tom Emerson wrote:

> I have a feeling that what it will come down to is actually converting
> the DocBook to another format and seeing how it goes and how much work
> it will be over time to maintain.

Just as an experiment, I spent some time investigating what it would take to convert our current DocBook manual into LaTeX.

I picked chapter 15 of the manual, because it is short.

The DocBook source for chapter 15:
http://trac.clozure.com/ccl/browser/trunk/source/doc/src/gc.xml

The DocBook markup formatted as HTML:
http://ccl.clozure.com/ccl-documentation.html#Understanding-and-Configuring-the-Garbage-Collector

Chapter 15, converted to LaTeX via dblatex and some fairly simple (though a little time-consuming) manual cleanup:
http://www.clozure.com/~rme/gc.tex

Note that this file uses defun.tex, which may be found at http://www.clozure.com/~rme/defun.tex.  This is from the sources for CLTL2.  There are a couple of weird lines in gc.tex to define macros used by defun.tex; these weird lines are also copied from the CLTL2 sources, namely from CLTL.sty.

The LaTeX, formatted as PDF:
http://www.clozure.com/~rme/gc.pdf

I don't think anyone can argue with the quality of the LaTeX output; it looks pretty great.

The LaTeX, formatted as HTML, obtained via "htlatex gc.tex" (from TeX4ht as included with the TeXLive 2009 distribution):
http://www.clozure.com/~rme/gc.html

The conversion of the defun environment isn't very successful;  perhaps the converter can be customized to do something better with it.  There are also other conversion tools that I did not investigate.

Compare the following LaTeX markup

\begin{defun}[Function]
egc arg

Enables the EGC if {\it arg} is non-\cd{nil}, disables the EGC otherwise.
Returns the previous enabled status.

Although this function is thread-safe (in the sense that calls to it
are serialized), it doesn't make a whole lot of sense to be turning
the EGC on and off from multiple threads...
\end{defun}

to the corresponding DocBook markup

      <refentry id="f_egc">
        <indexterm zone="f_egc">
          <primary>egc</primary>
        </indexterm>

        <refnamediv>
          <refname>EGC</refname>
          <refpurpose></refpurpose>
          <refclass>Function</refclass>
        </refnamediv>

        <refsynopsisdiv>
          <synopsis><function>egc</function> arg</synopsis>
        </refsynopsisdiv>

        <refsect1>
          <title>Arguments and Values</title>

          <variablelist>
            <varlistentry>
              <term>arg</term>

              <listitem>
                <para>a generalized boolean</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </refsect1>

        <refsect1>
          <title>Description</title>

          <para>Enables the EGC if arg is non-nil, disables the EGC
          otherwise. Returns the previous enabled status. Although this
          function is thread-safe (in the sense that calls to it are
          serialized), it doesn't make a whole lot of sense to be
          turning the EGC on and off from multiple threads ...</para>
        </refsect1>
      </refentry>


I personally find the LaTeX easier to edit because the markup notation is so much more compact.  I would submit that the custom defun environment could hardly be any simpler in any wiki notation I am familiar with.

The ability to define custom document structure (e.g., Steele's defun library) is also very useful.  I understand that it's possible to define custom DocBook elements, too:  http://www.docbook.org/docs/howto/#customizations talks about customizing DocBook 5.0.  (The CCL manual is in DocBook 4.5.)  It seems very complicated, though, and there's also the matter of updating the XSL stylesheets to know how to deal with the new elements/attributes/whatever.

Ideally, of course, we would get both good HTML and good PDF output from the markup.  It seems, however, that this is rarely (if ever) achieved in practice.  If we want the best PDF/printed output, then LaTeX is an outstanding choice.  The question is then whether we can get serviceable HTML from the LaTeX.

http://www.cs.cmu.edu/Groups/AI/html/cltl/cltl2.html is an online version of CLTL2;  it was converted with latex2html (which seems to be more-or-less obsolete now).  It is mentioned that many glitches were fixed by hand;  we obviously can't afford to manually fix up the HTML every time we need to rebuild the manual.

I think the CLTL2 HTML is satisfactory, so if we could duplicate its quality, I think LaTeX would work as a markup format for the CCL manual.