Re: [AD] new makedoc tool

[Elias Pschernig <elias@xxxxxxxxxx>]

On Tue, 2005-07-12 at 14:12 +1000, Peter Wang wrote:

> > 
> > What do you mean? You want the bar at the top and bottom also on the
> > front page?
> 
> I want "Next:", "Prev:", etc. to not jump around horizontally as I click
> through the pages.
> 
> > 
> > Oh, and is the .css also somewhere in the makedoc CVS module?
> 
> Yes, it's there.

Ah, yes, found it. Try adding this to the CSS:

div.navbar * td {
        width: 25%;
};

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

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

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

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

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

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

-- 
Elias Pschernig