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

[Brian Mastenbrook]

On 12/13/2009 1:51 PM, Tim Bradshaw wrote:
> On 12 Dec 2009, at 02:36, Ron Garret wrote:
>
>> There's a technology called S-expressions you might want to look
>> into.  S-expressions are kind of like XML, but with a much saner
>> syntax.  You don't have to manually match up your end tags, which
>> makes S-expressions much easier to compose and to read than XML.
>> There are a lot of tools for manipulating S-expressions, including
>> an editor called Emacs, and another one called Hemlock.  It is
>> borderline trivial to transform S-expressions into XML, or any other
>> format you like.  S-expressions have even been used as the base
>> syntax for a full-featured programming language called Lisp.  If you
>> haven't looked at it you really should. It's quite nifty.
>
> And here's a thing.  I once made my living teaching, and as a result
> had to write a lot of documents, usually in a tearing hurry.  I had a
> thing called HTOUT which I'd written before that, as a fairly trivial
> hack to embed HTML (really any SGML-family language with some caveats)
> into Lisp, using a fairly obvious syntax (there are several things
> that do this of course, and I make no great claims for HTOUT).  I
> found it *much easier* to write documentation *in this syntax* than
> XML, because XML is, frankly, such a pile of shit (and I say this as
> someone who worked with SGML in the early 90s: XML is, just, an
> improvement over SGML-based systems, but they haven't fixed any of the
> interesting stuff).  I wrote quite a substantial manual like this.
> Macros and editor support outweighed the requirement to put all the
> actual text in quotes.
>
> Later on, we had a system called DTML which used HTOUT's backend but a
> parser which was more oriented to text: the syntax looked like<em|
> this>  or<a :name "foo"|this>  (note no closing tags).  Between two of
> us we write a couple of hundred page manual in a week or so (of long
> days) using DTML.  It was almost as good for authoring as TeX and far
> better for the processing, unless all you ever wanted was paper output.
>
> It's not surprising that DTML was a better syntax for text than XML,
> what is surprising is that raw S-expressions are, as well.
>
> (I'm not offering DTML because the implementation needs a bunch of
> work to make its macros not be just completely mad, and I don't have
> time.)

I personally find editing text in S-Expressions to be incredibly 
cumbersome. Quite a lot of my code is mixed XML/S-Expressions done with 
a reader macro that allows me to write things like (<a href="test"> 
"Text!"), and while this works for layout in web applications I'd go mad 
trying to read things like "This is a bit of text that has \"quotes\" 
and \"\\"\" (backslashes) in it".

I hesitate to inject another suggestion into what seems to be an 
exercise in bikeshed painting, but I'd suggest that everyone take a look 
at the PLT documentation tool Scribble. It uses a texinfo-like syntax 
that has an equivalence to an ordinary S-expression based syntax. It's 
used to generate all of the PLT documentation, which means there is 
plenty of example source out there to see how well it works in practice. 
I personally find it easy to write and read, and don't see why a similar 
syntax couldn't be used for wiki-based documentation.

Here is the documentation on Scribble: 
http://docs.plt-scheme.org/scribble/index.html

Brian

-- 
Brian Mastenbrook
brian at mastenbrook.net
http://brian.mastenbrook.net/