Building TOCs - can this be in the LDP-Authors-Guide ?

[kevin@northants.lug.org.uk (Kevin Taylor)]

Hi,

I have recently posted a comment that I will be
writing a new mini howto (xdm/xterminals) - I
know that I could submit it in HTML, but I also
know how much time volunteers really have (I run
a LUG) - so I have tried to get a SGML version
done myself.

This is fine, and I now have some SGML sources
that produce HTML ok.

As a new user of DocBook, etc I have the
following comments on the LDP-Author-Guide, and
the facilities in general :

1. I am very confused about the relationships
between the different tools.  I use sgmltools
(debian) which is fine, but your examples in the
LDP-Authors-Guide use jade.  Perhaps a quick
summary of what are the 'backend/real work' tools
(jade, latex, etc) and what are the front end
tools (the sgmltools scripts - I assume)
and how they relate to each other may be
appropriate in your tools section.
2. I would recommend a sort of 'flow-chart' like
diagram illustrating the workflow - ie Front-end
Lyx/Emacs/vi whatever -> ASCII based SGML source
-> sgmltools -> backends -> outputs, etc, perhaps
then with each portion referencing the section in
the document that talks about that particular bit.

3. I echo the comments about a template - I found
the big-howto-template very useful in general,
but some of the tags were a little cryptic (but
that could have just been me :-)
4. The biggest 'hole' in the documentation, as
far as I am concerned, is how you actually end up
with the well-known format of the HMTL howtos 
- ie the fred-howto.html, fred-howto1.html, file
structure and the table of contents.  I have seen
lots of references to building indeces, but
cannot find out what I actually need to put in my
SGML source in order to produce the table of
contents.
I think that you use collateindex.pl but I don't
know what this actually does.  A template howto
that includes a TOC is very important in my
opinion.  It may well be worth actually providing
a recipe for 'building' the same template howto
into a HTML source - ie something that a brand
new user (like me) can blindly follow initially,
and then start to work out what the stages
mean later on.

Many thanks for this document - I got me writing
SGML very quickly.  I just need a bit of help
with the TOC and I am there !


Thanks,
Kevin Taylor,
Northants LUG.



--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org