Re: [AD] new makedoc tool

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2005-07-13, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> On Wed, 2005-07-13 at 23:08 +1000, Peter Wang wrote:
> > 
> > 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.

@sectN is implemented now, and so is @include file._tx.  You can use
@include whereever you would have otherwise written @sectN or
@chapter/@heading/@hnode.

I found that it was necessary to introduce "@end sectN" commands.
e.g.
	@sect1 Foo
	@include bar._tx

would turn `bar' into a subsection of Foo.  Whereas

	@sect1 Foo
	some text
	@end sect1
	@include bar._tx

would turn `bar' into a section at the same level as Foo.
@end commands are not needed normally.

One thing with @included files is that the overall document cannot have
duplicate section headings (due to cross-references).  Documents often
want to use the headings "Introduction" or "Contents".  I suppose a
solution can be found but probably the best thing is "don't do that".
Introductory text should just go at the very start of the document
without a heading (a good idea if the document will be @included, as it
will end up forming the text of a chapter or section).  "Contents"
sections should be automatically written by backends anyway.

Peter