Re: [AD] new makedoc tool

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2005-07-12, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> On Tue, 2005-07-12 at 14:12 +1000, Peter Wang wrote:
> 
> Ah, yes, found it. Try adding this to the CSS:
> 
> div.navbar * td {
>         width: 25%;
> };

Great!

> > I don't know if @externalfile is actually useful for non-HTML outputs.
> > As it is used now, it's only to link disparate documents into a master
> > web page by index._tx.  The referenced documents are not really part of
> > index._tx.
> 
> Well, in the case of the current allegro._tx, the PDF output should
> include all the @externalfiled things. So I think it already is used as
> @include. We don't need something to link to external files in HTML I
> think, can just place plain links instead.

Oh, you're right.  I'd forgot that allegro._tx uses @externalfile as
well.  It does make it a bit harder since you'd want to be able to
process the included documents separately as well.

> > > @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)
> > 
> > Hmm, I don't really like @end-pairing for sections.  It's too hard to
> > match them up.  My proposal is more like LaTeX/Texinfo:
> > 
> 
> @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.

> > @chapter Title		== @chapter\nTitle\n
> > @section Title		== @heading\nTitle\n
> > @subsection Title	== @hnode Title
> > @subsubsection Title
> > 
> > The equivalences to current syntax are shown to the right.  It doesn't
> > extend to arbitrary depth but IMHO you don't need that.  Most of the
> > target formats have limits, too.
> 
> 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?

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

> > Maybe splitting of HTML pages should be done in a smarter way.  I think
> > splits should be done at the second lowest level, e.g. if a subsection
> > contains subsubsections then it gets its own page.
> 
> But the bottom most are most important. Think e.g. of man output.
> @heading/@hnode would decide what is a manual page (or a split HTML
> page). Easier to add additional nesting above.

Man page output doesn't care about sectioning at all, nor does it have
any bearing on HTML output.  But you're partly right: often sections
have no subsections but should nevertheless be separate pages.

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

> > Again, I think there are two potential uses of @externalfile which must
> > be distinguished.
> > 
> 
> Yes, I think we only need one to include something. The other was just a
> hack in the current makedoc. But definitely should rename it to
> @include.

Ok.


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?

Peter