permuted index

[Russell Quin]

In article <1887 at ukma.UUCP> sean at ukma.UUCP (Sean Casey) writes:
>How do you generate the permuted index, as in the beginning of the Volume 1
>of the Unix manuals?

This gets asked quite regularly.  The best way is to do exactly what you have
done - ask someone else!   Actually, it's not too bad if you know at least the
basics of troff.  Here's a brief list and some VERY CUT DOWN examples to give
you (and anyone else who wants to know) a head start.
I'm posting this instead of using mail because in the past queries like this
always seem to herald a plethora of ``tell me too!!'' articles!
Please note that it's useless to ask people outside your site specifics since
the actual troff macros & command line options vary wildly depending on the
device and software you are using.
			- Russell

1	Use whatis(1) to generate the contents list.  You may be able to say
   man -k ''
to do this, or you may have to use apropos.  Failing that, you may have to
install the man database using makewhatis(1).
This will give you lots of lines like this:
cat(1)              - catenate and print files

2	Use ptx(1) to turn this into a Permuted Index.  This will give you lots
of lines like this:
.xx "" "cat(1)" "- catenate and print files" ""
.xx "and print files" "" "cat(1)              - catenate" ""
.xx "" "cat(1)              -" "catenate and print files" ""
.xx "" "- catenate and print" "files" "cat(1)             "
.xx "" "- catenate and" "print files" "cat(1)             "

3	write a troff macro called xx which deals with these lines.  Before you
recoil in horror (but if you are going to be a Unix-Wizard then you must learn
all the spells :-) ), there may already be one in /usr/man/man0 or /usr/skel.
If not, here is a simple example.
	.nf	\" turn filling off
	.na	\" don't justify the right margin!!!
	...	now set the tab stops.  You need to alter these for the device
	...	you are using.  A more complicated macro package would work it
	...	out for itself, but that would be too long to post.
	.ta 107mR 109mL
	...	Having set things up, here is the actual macro.
	...	Remember not to use "..." comments inside macro definitions,
	...	as they terminate them!
	...
	...	if you want rows of dots, you will have to insert a \\a where
	...	you want them.  See the ptx(1) entry for details on the format
	...	of its output.
	.de xx
	\\$1\t\\$2\t\\$3\\$5
	..

4	use troff/nroff/sroff/xroff/roff/titroff/ditroff to print the stuff.
For example, 
		x=/userpk/etc/req/sh/ptx
		ptx  -f -w 226 -b ${x}/break -i ${x}/ign |
		nroff -T8912c2 ${x}/ptx.mac - |
		bold |	# I put the names in bold
		col |	# for subscripts/superscripts
		pf -w226 -Hs5 -Fs5 |  # save paper.  Leave this out if
		# you don't have pf(1L).
		lpr -f2 -c4 -P dre # the dre8912 printer in font 2 and
		# compression ratio number 4 (226 chars/line)
		# for proofing.
So the complete command looks like
	whatis '' | ptx | troff | post-processors
-- 
		... mcvax!ukc!warwick!req  (req at warwick.UUCP)
"How beautiful are the feet of them that preach the gospel of peace..."