Re: [AD] new makedoc tool

[Elias Pschernig <elias@xxxxxxxxxx>]

On Wed, 2005-06-29 at 18:20 +1000, Peter Wang wrote:
> Hi,
> 
> If you watch the CVS commits list, you may have seen that I have written
> a new makedoc tool in Haskell.  It's sitting in the makedoc CVS module.
> 
> The idea was to write a relatively clean, declarative (and therefore
> easy to modify) parser which could handle most of the constructs used in
> existing makedoc documents.  The parser turns makedoc documents into a
> abstract syntax tree (using sweet-as algebraic datatypes).  Backends do
> not have to know the details of makedoc syntax _at all_; they only work
> with the AST, which is supposed to tell them everything they need to
> know.  For example, style tags like <em> and even C variable & function
> signatures in the '@@' lines are parsed.  Haskell won't let you forget
> to update a backend when the AST changes, so it's nice for maintenance.
> 
> Currently there exist [not completely polished] backends for:
> 
> 	- XML (that matches allegdoc.dtd, modulo extensions like subsections)

I guess, backends can also use the XML then. I'm curious how it compares
to the XML produced by the perl, python and C versions :) Will try it
out on the weekend..

> 	- LaTeX

Yay. Finally, we can produce proper PDF output. Does it support
arbitrary hierarchy? (._tx needs support for that first of course) It
could then be used for things like tutorials..

> 	- man pages
> 	- plain text
> 
> A DocBook backend is on the way.  The parser doesn't handle thanks._tx
> or external files yet.

Do you know if any of those can produce .info output?

> I hope this tool will be taken into consideration if we will be shipping
> pregenerated documentation in the future.

I hope so too. And I think, when doing so, we should also revise
the ._tx format slightly, there are just too many inconsistent things
(which therefore make it hard to use). My idea is, it should be as easy
to use as some wiki markup. The simpler the better.

-- 
Elias Pschernig