[Openmcl-devel] ccl manual (was Re: trace on recursive functions)
brian at mastenbrook.net
Sun Dec 13 20:30:35 UTC 2009
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
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:
brian at mastenbrook.net
More information about the Openmcl-devel