From owner-freebsd-doc Tue Aug 8 15:25:22 2000 Delivered-To: freebsd-doc@freebsd.org Received: from scientia.demon.co.uk (scientia.demon.co.uk [212.228.14.13]) by hub.freebsd.org (Postfix) with ESMTP id 2CFEE37BAAE; Tue, 8 Aug 2000 15:25:06 -0700 (PDT) (envelope-from ben@scientia.demon.co.uk) Received: from strontium.scientia.demon.co.uk ([192.168.91.36] ident=exim) by scientia.demon.co.uk with esmtp (Exim 3.15 #1) id 13MH4u-000BlS-00; Tue, 08 Aug 2000 22:38:28 +0100 Received: (from ben) by strontium.scientia.demon.co.uk (Exim 3.15 #1) id 13MH4x-000AC7-00; Tue, 08 Aug 2000 22:38:31 +0100 Date: Tue, 8 Aug 2000 22:38:31 +0100 From: Ben Smithurst To: Nik Clayton Cc: freebsd-doc@FreeBSD.org Subject: Re: No index in The FreeBSD Handbook? Message-ID: <20000808223831.T65753@strontium.scientia.demon.co.uk> References: <4.3.2.7.2.20000807173830.00b0adc0@mail.utexas.edu> <20000807181715.D34835@luna.osd.bsdi.com> <20000808105115.Q65753@strontium.scientia.demon.co.uk> <20000808191802.A99380@catkin.nothing-going-on.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2i In-Reply-To: <20000808191802.A99380@catkin.nothing-going-on.org> Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Nik Clayton wrote: > There's more to it than that. I understand (although it's not something > I've personally done) that there's an art to indexing. For example, there's > little point in indexing every occurence of the word "port" in the Handbook, > to try and direct people to information about ports. > > There are then some hoops to jump through to get the index included in the > document. > > More details at > > http://www.nwalsh.com/docbook/dsssl/doc/indexing.html > > *Please*, feel free to play around with this -- it's been on my list for a > while, and other stuff keeps pushing it out of the way. Hmm. Well, it all seems to work. Miracle. :-) I used this patch to doc.docbook.mk, so you can just set HAS_INDEX and have stuff done for you, as long as you add the appropriate entities to include genindex.sgml. (This patch breaks if you do 'make obj' before building to keep /usr/doc clean of crap. I don't know how to fix that, since you need an entity like and genindex.sgml needs to be created in /usr/obj/usr/doc/foo, not /usr/doc/foo. I also didn't test the patch with anything other than the default formats for the handbook (html-split).) Now, the harder part, is going through the Handbook and FAQ, adding the tags. At least if we got the basic support for indexes committed, people could think about indexing any new stuff they add. Index: doc.docbook.mk =================================================================== RCS file: /usr/cvs/doc/share/mk/doc.docbook.mk,v retrieving revision 1.16 diff -u -r1.16 doc.docbook.mk --- doc.docbook.mk 2000/07/18 16:30:45 1.16 +++ doc.docbook.mk 2000/08/08 21:28:11 @@ -25,6 +25,8 @@ # them need to be generated. Changing any file in # SRCS causes the documents to be rebuilt. # +# HAS_INDEX If defined, the document has an index. +# # ------------------------------------------------------------------------ # @@ -63,6 +65,10 @@ KNOWN_FORMATS= html html.tar html-split html-split.tar txt rtf ps pdf tex dvi tar pdb +.if defined(HAS_INDEX) +_genindex_sgml= genindex.sgml +.endif + # ------------------------------------------------------------------------ # # Look at ${FORMATS} and work out which documents need to be generated. @@ -170,14 +176,22 @@ .MAIN: all all: ${_docs} + +.if defined(HAS_INDEX) +${_genindex_sgml}: ${SRCS} ${LIB_IMAGES} + touch ${_genindex_sgml} + ${JADE} -V html-index -ioutput.html ${JADEOPTS} -d ${DSLHTML} -t sgml ${MASTERDOC} + perl ${PREFIX}/share/sgml/docbook/dsssl/modular/bin/collateindex.pl \ + HTML.index > ${_genindex_sgml} +.endif -index.html HTML.manifest: ${SRCS} ${LIB_IMAGES} +index.html HTML.manifest: ${SRCS} ${LIB_IMAGES} ${_genindex_sgml} ${JADE} -V html-manifest -ioutput.html ${JADEOPTS} -d ${DSLHTML} -t sgml ${MASTERDOC} .if !defined(NO_TIDY) -tidy -i -m -f /dev/null ${TIDYFLAGS} `xargs < HTML.manifest` .endif -${DOC}.html: ${SRCS} ${LIB_IMAGES} +${DOC}.html: ${SRCS} ${LIB_IMAGES} ${_genindex_sgml} ${JADE} -ioutput.html -V nochunks ${JADEOPTS} -d ${DSLHTML} -t sgml ${MASTERDOC} > ${.TARGET} .if !defined(NO_TIDY) -tidy -i -m -f /dev/null ${TIDYFLAGS} ${.TARGET} @@ -200,10 +214,10 @@ ${.CURDIR:T}.pdb: ${DOC}.pdb ln -f ${DOC}.pdb ${.CURDIR}.pdb -${DOC}.rtf: ${SRCS} +${DOC}.rtf: ${SRCS} ${_genindex_sgml} ${JADE} -Vrtf-backend -ioutput.print ${JADEOPTS} -d ${DSLPRINT} -t rtf -o ${.TARGET} ${MASTERDOC} -${DOC}.tex: ${SRCS} +${DOC}.tex: ${SRCS} ${_genindex_sgml} ${JADE} -Vtex-backend -ioutput.print ${JADEOPTS} -d ${DSLPRINT} -t tex -o ${.TARGET} ${MASTERDOC} ${DOC}.dvi: ${DOC}.tex -- Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D FreeBSD Documentation Project / To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message