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

[Philippe Sismondi]

On 2009-12-11, at 5:34 AM, Tim Bradshaw wrote:

> On 10 Dec 2009, at 19:11, R. Matthew Emerson wrote:
>
>> To misuse a chemistry term, the activation energy required to create
>> or edit is wiki page is much lower than that for editing the manual.
>>
>> The manual is in DocBook, and it is rather painful to edit (at least
>> for me it is).  Emacs's nXML mode keeps me from producing invalid
>> structure, but still, DocBook is big and complicated.
>>
>> With the wiki, it's easy to just throw something up there.
>> Eventually, important stuff on the wiki makes it back into the
>> manual, or ought to.  TRACE is one example that made the jump.  Just
>> looking now, I see that the documentation on HEAP-UTILIZATION is
>> another candidate that should make the leap to the manual.
>
> Is there any way to make the wiki *be* the manual? I don't know enough
> about the specific wiki here, but I'm thinking of some approach where
> you construct some kind of view of a lot of wiki pages which
> essentially is the manual (obviously this would not be "all pages" it
> would be some subset).  That's probably a bit less powerful than using
> some dedicated system like DocBook but it means there is a single
> source of information, and it's easier to update as well.

It is important to me that there be an offline form of the  
documentation. I often work on the commuter train or at a cabin  
without an Internet connection. Of course, the current manual is  
available as one big web page (which works fine for me). But if the  
current wiki setup were the only form of documentation I would find it  
less useful.

The reason I have had success with docbook in the past is that I use a  
high end tool (Arbortext Editor) to edit docbook content. I would hate  
to use only emacs+nXML for this purpose. Transforming docbook to html  
or pdf is (can be) highly automated and hence easy. So it's the  
author's effort in creating and maintaining the docs that is the issue  
here; I'm sympathetic on that score. There is little doubt that  
difficult to use tools = poorer documentation.

- P -