[Openmcl-devel] ccl manual (was Re: trace on recursive functions)
gz at clozure.com
Fri Dec 11 17:07:50 UTC 2009
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:
<refpurpose>This function does stuff.</refpurpose>
<function>some-function</function> => result
<para>More detail about what this function does blah blah blah</para>
More information about the Openmcl-devel