Re: [AD] new makedoc tool

[Elias Pschernig <elias@xxxxxxxxxx>]

On Wed, 2005-07-13 at 23:08 +1000, Peter Wang wrote:
> > 
> > They would ignore the upper ones. E.g. a man page will always correspond
> > to a heading, and don't care at all in what sections and chapters this
> > heading may be. It's like it already works with @chapter.
> 
> I don't think dropping content is a valid solution in general.

Yes, true. At the worst, I would simply tell somewhere in the makedoc
manual the limitations for various formats (6 nesting levels for HTML
output, 4(?) for standard Latex).

> > Well, the reason I'd like it is that it makes @include easier, in case
> > we want to be able to @include something, but at the same time use it as
> > standalone file. In my idea, if it uses just @section (and @end), than
> > it would work automatically. The first @section woud be the top level
> > section when used standalone, and else be whatever subsection it is,
> > when included. (@chapter would just be an alias for @section, so also no
> > problem.) Didn't think about if it would be confusing. Maybe with
> > @include, it's not that much of a problem. And we could easily have
> > @chapter, @section, @subsection and so on, but they would just all by
> > synonyms.
> 
> That would work nicely.  If we name them as @sect1, @sect2, etc. (like
> DocBook) then the automatic raising/lowering would seem less strange.
> How's that?
> 

Sounds good.

I just want to make sure this won't be only able to parse allegro._tx
and nothing else, but be somewhat generally useful :)

All the things we couldn't do previously due to makedoc's limitations
should now get possible during 4.3.x.. like using this for other
projects, include a tutorial into the Allegro docs, have different HTML
versions (e.g. with user comments), or even something like a wikified
version which users can modify, and then patches are auto-created (and
applied or rejected and resynched).

-- 
Elias Pschernig