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

[Steve Núñez]

Gentlemen,

I must have missed the start of this (well, glossed over it hoping it was a
brief thread).

I can't help but think that going from DocBooks nicely ordered and
semantically correct format to something else is anything but a step
backward. 

We use docbook for a lot, and it certainly can be a PITA, but it's better
than any alternatives when you weigh everything up.

A good XML editor can make this job much, much easier.

    - Steve


On 12/12/09 4:22 AM, "R. Matthew Emerson" <rme at clozure.com> wrote:

> 
> 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-th
> e-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.
> 
> 
> _______________________________________________
> Openmcl-devel mailing list
> Openmcl-devel at clozure.com
> http://clozure.com/mailman/listinfo/openmcl-devel

-- 

Level 31
6 Battery Road
Singapore 049909

Phone:  +65 6321 9115
Mobile: +65 9679 8360
http://illation.com.sg