On Fri, 1 Mar 2002, Jeremy C. Reed wrote:
> Often the section numbers in the spec and FAQ change.
I have deliberately not changed any FAQ numbers. However, when I re-did
the FAQ for Exim 4 I renumbered it because there was so much change to
the content. I don't intend to change numbers as it gets edited.
> Sometimes this makes
> it difficult to point out specific documentation. For example,
> FAQ.html#SEC315 used to be useful for virtual domains, then later it was
> SEC372.
Ah, you mean HTML references. Those would be hard to maintain because
the HTML is generated from a text source, and it just allocates
cross-references automatically. So it I insert a new item in one
section, it will change these. The best way to reference the FAQ is to
give the Qxxxx number. These won't change (apart from the 3/4 change
mentioned above).
> Philip - Would it be difficult for the documentation to use non-changing
> section numbers?
It would be very constricting not, for example, to be able to put in a
new chapter or section in an appropriate place in the manual.
> And speaking of documentation: if you read that a type is "host-list",
> "string-list", "domain-list", etc., it is difficult for someone new to the
> spec (or who never read it completely) to search and find definitions for
Good point.
> Nigel - Also, it would be nice if the search index for the spec would show
> these hyphenated keywords also.
That's for me rather than Nigel. The index is generated when I prepare
the documents. It's trivial to add "domain-list see domain list", for
example.
--
Philip Hazel University of Cambridge Computing Service,
ph10@??? Cambridge, England. Phone: +44 1223 334714.
