Date: Wed, 28 Mar 2001 22:41:26 -0800 (PST) From: Murray Stokely <murray@osd.bsdi.com> To: Nik Clayton <nik@freebsd.org> Cc: <freebsd-doc@freebsd.org> Subject: Re: Indexing the Handbook Message-ID: <Pine.BSF.4.31.0103282230500.8770-100000@meow.osd.bsdi.com> In-Reply-To: <20010223144043.A46865@canyon.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
This short thread died out a month ago, but there was never any resolution, soo.. On Fri, 23 Feb 2001, Nik Clayton wrote: % > <indexterm><primary>bounds checking</primary></indexterm> % % My main concern is that in talking with a few people at various % conventions it seems that getting a good index involves more than just % sprinkling <indexterm> liberally around the document. % % I've got no idea how we select good terms to index, and again, the % feedback I've had suggests that it's much more an art than a science. % Which probably means we can't write rules and procedures for it :-) % % Do we also run the risk of having lots of different index terms, all % subtly different? I don't know. This is very easy to correct in practice. The HTML index that gets created is of course in alphabetical order, so very similar index terms that should probably be compounded are very easy to spot, and in fact I did this for several terms in my original patch (all relating to singular vs plural use of a noun). % Is this something we could use entities for? % % <!ENTITY index.p.stack_frame % "<indexterm><primary>stack frame</primary></indexterm>"> % % and then write % % &index.p.stack_frame; % % in the documentation? % % As I say, I don't know. I'm not sure what the best way is either, but I think this is a very minor style nit when compared with the complete absence of an index in our printed documentation. Replcaing the indexterms with entities is just a matter of search and replace, so we can easily change our minds later once we've actually got some experience working with an index. I would like to commit this patch to the Developers Handbook and continue adding index terms to that document. If things get ugly then we can find a better way before touching the FreeBSD Handbook. Are there any objections to me proceeding with this? - Murray To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.4.31.0103282230500.8770-100000>