Date: Fri, 1 Mar 2002 16:10:45 +0000 From: Ceri <setantae@submonkey.net> To: doc@FreeBSD.org Subject: The FAQ and IndexTerm Message-ID: <20020301161045.GA43649@submonkey.net>
next in thread | raw e-mail | index | archive | help
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 <qandaentry> 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 @@ </answer> </qandaentry> + <indexterm class="startofrange" id="other-info-sources-index"> + <primary>further information</primary> + </indexterm> <qandaentry> <question id="other-info-sources"> <para>What other sources of information are there?</para> @@ -590,6 +593,8 @@ site.</para> </answer> </qandaentry> + <!-- EndOfRange IndexTerm; shouldn't be closed --> + <indexterm class="endofrange" startref="other-info-sources-index"> </qandaset> </chapter> __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 @@ </chapter> &bibliography; + + <indexterm zone="other-info-sources"> + <primary>further information</primary> + </indexterm> </book> __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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020301161045.GA43649>