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

[Gail Zacharias]

At 12/11/2009 11:15 AM, Robert Goldman wrote:
>Tom Emerson wrote:
> > On Fri, Dec 11, 2009 at 11:04 AM, Gail Zacharias <gz at clozure.com> wrote:
> >> That's more than a quibble... My whole point was that humans 
> would only have
> >> to edit a very simple wiki format.  If the wiki is frozen and 
> humans have to
> >> edit a source document with some overwrought syntax, that's a different
> >> proposal.
> >
> > True: I guess my experience with going from relatively simple markup
> > in the wiki to the richer format of DocBook or LaTeX will end up being
> > quite frustrating and problematic.
> >
>
>Agreed.  The wikis don't "know" when they are talking about, e.g., a
>function, although docbook and texinfo do.  You can't have very simple
>wiki format and have semantic markup (and good indexing) at the same time.

The wiki may not know, but we do.  That's why I suggest agreeing to 
some conventions and using them in all our doc in the wiki.  Yes, the 
wiki won't enforce the conventions, but that's the nature of weak 
typing, we're used to it, no? We'll notice soon enough if the doc 
comes out looking wrong.

Just to throw out an example, I can certainly envision a lisp program 
being able to notice and automatically convert a convention like 
this, similar to what we currently write in the some of the wiki doc:

[Function] '''`some-function arg1 arg2 => result`'''
This function does stuff[[BR]]
More detail about what this function does blah blah blah
----

into what we currently write in the manual sources:

<refentry id="f_some-function">
   <indexterm zone="f_some-function">
     <primary>some-function</primary>
   </indexterm>
   <refnamediv>
     <refname>some-function</refname>
     <refpurpose>This function does stuff.</refpurpose>
     <refclass>Function</refclass>
   </refnamediv>
   <refsynopsisdiv>
     <synopsis>
       <function>some-function</function> => result
     </synopsis>
   </refsynopsisdiv>
   <refsect1>
     <para>More detail about what this function does blah blah blah</para>
   </refsect1>
</refentry>