Xref: utzoo comp.text:2624 comp.sources.wanted:5310 comp.misc:3838
Path: utzoo!utgpu!water!watmath!clyde!att!osu-cis!tut.cis.ohio-state.edu!rutgers!cmcl2!phri!cooper!dasys1!jpr
From: jpr@dasys1.UUCP (Jean-Pierre Radley)
Newsgroups: comp.text,comp.sources.wanted,comp.misc
Subject: Re: Wanted: Documentation Indexing Tools
Keywords: Nroff-based indexing subj ndx
Message-ID: <7028@dasys1.UUCP>
Date: 18 Oct 88 15:30:19 GMT
References: <4597@brspyr1.BRS.Com> <6829@dasys1.UUCP> <2119@cuuxb.ATT.COM>
Reply-To: jpr@dasys1.UUCP (Jean-Pierre Radley)
Organization: TANGENT
Lines: 116

In article <4597@brspyr1.BRS.Com> bob@brspyr1.BRS.Com (Bob Armao) writes:
>    We use nroff with our own customized macros to construct  and
>    format a permuted index...
>
>    I'm looking for an approach (public domain or otherwise) that
>    will  enable  us  to  produce  a more traditional-looking and
>    effective  index.   For  now  we  have  to  live  within  the
>    restrictions of nroff and family.

Apologies to all if I am double-posting this, but I am still a bit of a
novice at netnews...


Here is how I handle indexing from nroff sources. The scheme is
originally described in Bourne's "The UNIX System".

I define these two macros and include them in a file .macros
(along with other macros pertinent to the project at hand):

	.deIX			\" index macro
	.tm \\$1\a..   \\n(H1-\\nP
	..
	.deCX			\" choose index item macro
	.IX "\\$1, \\$2"
	.IX "\\$2, \\$1"

The first line in each source file is:

	.if!\w@\*(tL@ .so .macros

This shell script (where <TAB> is shown here in place of the actual tab
character itself, i.e. hex 09) assembles all my chapters:

	: broff
	# run files through nroff with jpr's mm macros  to
	# `book', including index at end

	nroff -rO0 -rW64 -mmjpr ch.* > .book 2> .index 

	sed "
	s/.*/&~+~&/
	:repeat
	s/\\\\[fs][+-]*.\(.*~+~\)/\1/
	t repeat
	" .index | sort -fd | sed "s/.*~+~//" | awk '
	BEGIN	{ print ".af P a"
		  print ".PH @@\fBINDEX\fR@@"
		  print ".PF @@\\\\\\\\nP@@"
		  print ".TS"
		  print "l r."
		  print }
		{ print }
	END	{ print ".TE" }
	' | tbl | nroff -rO0 -rW64 -mmjpr >> .book

	sed "
	s/^\(.\)/<TAB>\1/
	:spc2tab
	s/<TAB>        /<TAB><TAB>/
	t spc2tab
	" .book > book
	rm .book .index

At any place in the source file where I judge an index reference
would be useful, I imbed a call to the CX macro. Here's a fragment
from one of my source files:

	.P
	In that case why have to refer to the files on that drive
	as "/hdN/appl/.../.../..."?
	Why not dispense with the "/hdN" part?
	.CX "/appl" "changing /hdN to"
	.CX "/hdN" "changing to /appl"
	.P
	.I
	Case 1: Changing mount directory /hdN to /appl
	.R

The .index file will have in it (where <SOH> represents ^A, hex 01):

	\fB/etc/default/pfpath\fR, secondary drive name<SOH>..   1-4
	secondary drive name, \fB/etc/default/pfpath\fR<SOH>..   1-4
	/appl, changing /hdN to<SOH>..   1-4
	changing /hdN to, /appl<SOH>..   1-4
	/hdN, changing to /appl<SOH>..   1-4
	changing to /appl, /hdN<SOH>..   1-4
	tar, moving hierarchies<SOH>..   1-4
	moving hierarchies, tar<SOH>..   1-4

which are various index references I have created. As the source
is being formatted, these entries get created with the chapter
number (1), and with the output page number (4) within that chapter.
Finally, all the chapters are assembled into one file, at the end
of which appear these fragments:

	512 bytes, blocking.......................................   1-6
	/appl, changing /hdN to...................................   1-4
	background processes, wait................................   7-4
	....
	blocking, key segment.....................................   1-7
	changing /hdN to, /appl...................................   1-4
	changing to /appl, /hdN...................................   1-4
	...
	fortune cookies, /etc/rc.user.............................   1-5
	/hdN, changing to /appl...................................   1-4
	index, 13-byte overhead...................................   3-7
	...

Should any of the arguments to .CX contain font-change stuff, this
will carry through to the final index. In the actual case, I have
/etc/rc.user in boldface in the final text, and in the index as well.
-- 

Time is nature's way of				Jean-Pierre Radley
making sure that everything			jpr@dasys1.UUCP
doesn't happen all at once.			CIS: 76120,1341