[cl-typesetting-devel] Re: [cl-pdf-devel] Cl typesetting and cl-pdfdocumentation creation

[Marc Battyani]

Klaus Weidner wrote:


> On Mon, May 17, 2004 at 09:56:48AM +0200, Marc Battyani wrote:
> > I agree with that. A documentation in a bad format is better than no
docs in
> > a nice format ;-)
> > Though of course it would be better to use a format that can be
converted
> > to/processed by cl-typesetting. So if anybody already have some kind of
user
> > friendly syntax that could be used please raise your hand!
>
> I think the XHTML to cl-typesetting converter I've been working on would
> be an option for this. The table support is still a bit rudimentary, but
> this could be extended fairly easily.

Tables you said?

> However, if you want the documentation to directly demonstrate advanced
> formatting tricks and features, it would probably need to be done
> directly in low-level cl-typesetting code.
>
> Personally, I quite like the Perl Plain Old Documentation (POD) format,
> since that has very non-intrusive markup and is pleasant to edit. POD
> supports formatter specific sections, so with a bit of hacking you could
> do this:
>
> =head3 Another example
>
> Here's a more complex example:
>
> (... fancy Lisp code ...)
>
> for which the rendered output looks like this:
>
> =begin cl-typesetting
>
> (... fancy Lisp code ...)
>
> =end cl-typesetting
>
> Normal text follows
>
> I'll try to get the XHTML converter into releasable state this week
> (nothing major, just some dead code removal and maybe a few docstrings),
> and send it to the list. I'm also planning to write a native Lisp POD
> parser to remove the Perl dependency (also, pod2html is rather braindead,
> and I usually use the detour pod2latex -> latex2html).

A format allowing to mix text with the cl-typesetting raw-syntax is a good
idea.

Marc