On Mon, 3 Oct 2005, Marc Sherman wrote:
> No, I meant indexing the individual variables -- ie: an index entry
> "local_part" that points to the local_part definition, similar to the way
> individual options are indexed in the routers and transports.
All such entries would point to section 11.9.
> > I suppose, with a lot of work, I could put in an index entry for every time
> > a specific variable is mentioned in the manual. Perhaps it would be worth
> > doing that work.
>
> That would be overkill, IMO.
Well, if you have an entry that says
$local_part 111
you might think that page 111 was the only place in the book where
$local_part was mentioned. This is, I think, poor indexing. I'd rather
do the full job or nothing at all.
> > The next edition of the manual is going to be prepared by the new method,
> > using XML. The PS/PDF version's index will be by page, as before, but the
> > HTML index will point only to the section (i.e. to 11.9) because that's what
> > the processing software does.
>
> Does that apply to the options on routers/transports only being indexed to the
> "Private options for XXX" section header? If so, I think that's a pretty big
> regression, IMO.
Of course it is. It is not the only big regression that will occur. I
made test documentation by the new method quite some time ago and made
it available for comment. Nobody objected, but I didn't really expect
that people would look in detail.
> Being able to link to a specific option is very useful when
> answering questions on this list. Can the processing software not support a
> third level of section heading, which renders without numbers, and can be used
> for option and variable headings?
Possibly, but I rather doubt it. Option headings in the new arrangement
are actually one-line tables. It's some months since I looked at this
stuff; I'll be picking it up again very shortly when I start on the 4.60
manual. It maybe that (a) I can find away round it or (b) the world has
improved in the mean time.
Otherwise, if you can tell me what to install to turn DocBook XML into
HTML with the right kind of indexing, as long as it's free software, I
will be delighted. Or maybe there's a way of changing the XSL
stylesheets, about which I do understand fractionally more now that I've
bought and read the book.
To be honest, I am expecting howls of anguish at the next documentation
release. I'm unhappy with many aspects of it, but I don't want to leave
Exim's documentation in a very non-standard source format.
--
Philip Hazel University of Cambridge Computing Service,
ph10@??? Cambridge, England. Phone: +44 1223 334714.
Get the Exim 4 book: http://www.uit.co.uk/exim-book
