Re: [AD] new makedoc tool

[Elias Pschernig <elias@xxxxxxxxxx>]

On Sun, 2005-07-10 at 23:47 +1000, Peter Wang wrote:
> Ok, now we have a native HTML backend (bar index generation). e.g.
> 
>    http://web.aanet.com.au/tjaden/dev/makedoc/html/,,top.html
>    http://web.aanet.com.au/tjaden/dev/makedoc/html/,,article.html
> 

Good work!

> (don't mind the weird names either)
> 
> I mainly swiped asciidoc's supplied stylesheet.  If someone would like
> to make a better one, the file is called `makedoc.css' in the same
> directory.  I'd be happy to make any changes to the generated files to
> accomodate.  At the least, I'd like to know how to keep the "navigation
> bar" links from moving around from page to page.

What do you mean? You want the bar at the top and bottom also on the
front page?

Oh, and is the .css also somewhere in the makedoc CVS module?


And since this is nearing a finished state, it's time to revisit the
bugs which made the old makedoc so bad, they should not be carried over
to the new one.

1. One thing is the @externalfile. It's where both Grzegorz and me
failed to fix the PDF output.. non-HTML formats so far simply ignore
@externalfile. The same problem would arise with an HTML all-on-one-page
output.

2. Another, related, problem is that some things need more nesting depth
than 3 levels. E.g. currently, there's no way something like
http://www.glost.eclipse.co.uk/gfoot/vivace/vivace.html#Index could be
done with _tx. But, it should work like this (just as an example):

in allegro._tx:
@chapter Tutorials
@externafile vivace._tx

And in vivace._tx:

@document_title=Vivace
@chapter User Input
@section Keyboard
@heading Using the Keyboard

So in this case, a single @section element would do. My proposal is
this:

@chapter - top level structuring, but could as well deprecate it, and
supercede by the @section comand below

@section/@end - nested structuring, you can have arbitrary recursive
@section/@end pairs inside a @section/@end pair.

@heading/@hnode - like now, bottom-most levels (and e.g. point of split
for single-page HTML)

This would also solve the @externalfile problem, since a @section in an
included ._tx file would automatically have the right nesting level
below whereever it was included. @chapter probably would be converted to
@section on the fly, if it is encountered in an included file.

3. Hm, there was some others, but the above was why I started myself
working on a makedoc replacement. Can work on the other stuff later
(e.g. things like &lt instead of &lt; or <startblock> <endblock> :P)

-- 
Elias Pschernig