From owner-freebsd-doc Fri Mar 1 8:11:11 2002 Delivered-To: freebsd-doc@freebsd.org Received: from relay3-gui.server.ntli.net (relay3-gui.server.ntli.net [194.168.4.200]) by hub.freebsd.org (Postfix) with ESMTP id D99CC37B402 for ; Fri, 1 Mar 2002 08:10:59 -0800 (PST) Received: from pc4-card4-0-cust162.cdf.cable.ntl.com ([80.4.14.162] helo=rhadamanth.private.submonkey.net ident=mailnull) by relay3-gui.server.ntli.net with esmtp (Exim 3.03 #2) id 16gpcY-0001y6-00 for doc@freebsd.org; Fri, 01 Mar 2002 16:10:58 +0000 Received: from setantae by rhadamanth.private.submonkey.net with local (Exim 3.35 #1) id 16gpcL-000BSb-00 for doc@FreeBSD.org; Fri, 01 Mar 2002 16:10:45 +0000 Date: Fri, 1 Mar 2002 16:10:45 +0000 From: Ceri To: doc@FreeBSD.org Subject: The FAQ and IndexTerm Message-ID: <20020301161045.GA43649@submonkey.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.3.27i Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org All, As promised, today is the day when I start work on adding IndexTerm elements to the FAQ (although a close friend has suffered a bereavement, so I probably cannot actually add any today; but I can at least kick off this discussion). According to http://www.docbook.org/tdg/en/html/indexterm.html, the indexterm element is not valid within tags, which as I understand (and I could be very wrong) leaves me with the only way of doing this to be adding IndexTerm ranges as described on the same page. Which there are two ways of doing: 1) Use the StartOfRange class attribute, and produce stuff which looks like this : __start first_way.diff --- book.sgml.old Fri Mar 1 15:29:03 2002 +++ book.sgml Fri Mar 1 15:44:32 2002 @@ -577,6 +577,9 @@ + + further information + What other sources of information are there? @@ -590,6 +593,8 @@ site. + + __end first_way.diff Now this is a bit horrible. It's hard to do, it's hard to maintain, and I think it's ugly. Which brings us to the second way : 2) Use the Zone attribute, which produces stuff like this : __start second_way.diff --- book.sgml.old Fri Mar 1 15:29:03 2002 +++ book.sgml Fri Mar 1 15:31:09 2002 @@ -12334,4 +12334,8 @@ &bibliography; + + + further information + __end second_way.diff I hope you'll agree this is much nicer, and easier to maintain. The URL above mentions that when done in this way, the IndexTerm elements can quite happily live in another file, which make it even nicer, as if this could be done then I could happily knock that file together and not have to worry about anyone making major changes to the FAQ and upsetting my patchset. Also, it would make it more easily maintainable. Presumably there needs to be some magic somewhere to make this work though, and I don't know how to do that - is it as simple as adding SRCS+= index.sgml to the Makefile and doing something similar to the Handbook's book.sgml ? (At this point I am querying my usage of the word "simple" there...) So I would like some input on which way people would prefer to see this done, and also on how I make the second one happen (I'm very confident it will turn out to be the preferred solution). Thank you for your attention, Ceri -- keep a mild groove on To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message