Re: [AD] new makedoc tool

[Elias Pschernig <elias@xxxxxxxxxx>]

On Wed, 2005-07-13 at 00:41 +1000, Peter Wang wrote:
> > 
> > @chapter/@endchapter already are paired, that's why I'd have made
> > @section paired as well.
> 
> @endchapter was only used once and, honestly, I don't know why.

The reason was to mark the stuff after it to be not in the chapter -
i.e. there's the Tools chapter, with some headings in it, and after
that, there's the heading "Community", which is not part of any chapter.

> > 
> > Yes, and why should we inherit such limits? The exporter to a limited
> > format would deal with it, but not the source format itself.
> 
> What should backends do if they hit the limit?

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.

> > It's
> > exactly what made the old makedoc so bad - it merged the bad features of
> > all supported output formats: Newlines are relevant for text output,
> > sections depth is limited for texinfo output, and so on..
> 
> As I said, I don't think you actually need *arbitrary* nesting.  It just
> gets confusing.  Vivace was written in texinfo, and it seems to be fine.

Hm, well, don't know. I never liked the fact about the limited
subsections in latex - I think I even hit some sort of limit once and
had to fiddle around in the .tex code to get it to make an extra
subsubsubsection or something :P But yes, there's no real reason.. I'm
just programming for too long, where arbitrary limits always seem bad.

> > >   Chapters with only a
> > > single section should result in one page, and chapter headings without
> > > text of their own should appear on the same page as the first section.
> > 
> > Well, it wouldn't be flexible enough I think. E.g. vivace couldn't
> > texified with it.
> 
> I don't understand why the HTML backend's choice of how to split files
> has anything to do with that.

Yes, sorry, I was answering to the wrong quote above I guess. vivace is
just an example of something I think makedoc should be able to do.. has
nothing to do with the splitting specifically though..


> Now, separate from the limited nesting issue, I don't have anything
> against collapsing all the sectioning commands into "@section", except
> that figuring out what a lone "@end" command closes off is going to be a
> pain (like #endifs without indentation).  Apart from forcing you to
> write "@end Some Title", is there some other option?

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.

For example, grabber._tx could look like this:

@chapter The Grabber
...
@section Menu commands
...
@heading File commands
...
@hnode Open
...

And makedoc grabber._tx would produce standalone HTML, PDF, whatever for
it. Now, allegro._tx would contain this:

@chapter Tools
...
@include grabber._tx
...

And now, the whole grabber document would automatically fit, although in
the actual HTML or latex outputs, its sections would he shifted one
down. In e.g. the XML, we could just have a nested <section></section>
as well.

Anyway, it just seems like a nice idea to me. Superior to HTML and
Latex :)

-- 
Elias Pschernig