From owner-freebsd-doc Wed Mar 28 22:41:41 2001 Delivered-To: freebsd-doc@freebsd.org Received: from meow.osd.bsdi.com (meow.osd.bsdi.com [204.216.28.88]) by hub.freebsd.org (Postfix) with ESMTP id 3B5E837B71A; Wed, 28 Mar 2001 22:41:39 -0800 (PST) (envelope-from murray@osd.bsdi.com) Received: from localhost (murray@localhost) by meow.osd.bsdi.com (8.11.2/8.11.2) with ESMTP id f2T6fQM17535; Wed, 28 Mar 2001 22:41:27 -0800 (PST) (envelope-from murray@osd.bsdi.com) Date: Wed, 28 Mar 2001 22:41:26 -0800 (PST) From: Murray Stokely To: Nik Clayton Cc: Subject: Re: Indexing the Handbook In-Reply-To: <20010223144043.A46865@canyon.nothing-going-on.org> Message-ID: X-PGP-Fingerprint: E2CA 411D DD44 53FD BB4B 3CB5 B4D7 10A2 0E45 1F7D MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org This short thread died out a month ago, but there was never any resolution, soo.. On Fri, 23 Feb 2001, Nik Clayton wrote: % > bounds checking % % 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 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? % % stack frame"> % % 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