Re: [AD] new makedoc tool

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


On 2005-07-11, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> On Sun, 2005-07-10 at 23:47 +1000, Peter Wang wrote:
> > 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?

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.

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

Perhaps you're thinking of splitting huge documents into more manageable
pieces?  We probably want an @include mechanism for that.  To me, this
is different to @externalfile in that the included files would be
considered part of the same document.  You wouldn't parse the included
files independently.

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

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

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

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

Peter





Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/