Date: Tue, 8 Aug 2000 22:38:31 +0100 From: Ben Smithurst <ben@FreeBSD.org> To: Nik Clayton <nik@freebsd.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: No index in The FreeBSD Handbook? Message-ID: <20000808223831.T65753@strontium.scientia.demon.co.uk> In-Reply-To: <20000808191802.A99380@catkin.nothing-going-on.org> 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>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <!ENTITY genindex.sgml SYSTEM "genindex.sgml"> 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 <indexterm> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000808223831.T65753>