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

[Klaus Weidner]

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.

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).

-Klaus