[comp.text] troff cross referencer

budd@mist.cs.orst.edu (Tim Budd) (09/12/88)

Here is an idea that is so simple I wonder it isn't more widely used.
(so simple in fact I'm sure I'm not the first one to discover it).

We can use the .sy command in ditroff, and a trivial shell script,
to make an arbitrary cross referencer.  This cross referencer can be used in 
a pipe, just like tbl, eqn, pic, bib and the rest.  The system needs only
two strings and three macros.

The first macro creates our cross reference file (I will use names suitable for
use with the -mm macros - other macro packages may need other names to
avoid clashes).  Usage is .RX file-name
	.de RX
	.ds XF \\$1
	.sy echo >\\*(XF
	..

The next macro takes a string, and makes a sed command line to change
occurrences of this string to whatever happens to be in the string XS.
	.de LA
	.if !'\\*(XF'' .sy echo /L[AP]/!s/\\$1/\\*(XS/g >>\\*(XF
	..
(bit of protection, we don't do anything if there hasn't been a prior RX,
and we don't modify LA or LP lines).

Another macro does the same thing, only using page numbers instead of XS.
	.de LP
	.if !'\\*(XF'' .sy echo /L[AP]/!s/\\$1/\\n(.P/g >>\\*(XF
	..

I'll talk about how XS gets set in a moment.
Usage is to put a .LA after anything you want labelled, with a unique
string that will be used as the cross reference tag.  As follows
	.H 1 "An Important Idea"
	.LA ideaSection
	.LP ideaSectionPage
	...
	... remember back in section ideaSection on 
	page ideaSectionPage we discussed ...

Now, all that remains is to get the string XS set up correctly.
This can be done by adding on to the end of macros which set things you
might want to cross reference.  Such as headings:
	.de HX
	.ds XS \\*(}0
	..
Figures:
	.am FG
	.ds XS \\n(Fg
	..
footnotes, tables, and the like.

Now, running this all through ditroff creates, in the file named in the RX
command, a set of sed command lines which convert the cross reference names
into the appropriate values.  To complete the system, therefore, all we
need is a script which invokes sed.  I call mine xroff, and here it is:

:
: xroff - troff cross reference program
: written by tim budd, September 1988
:
if test 0 -eq $#
then
	echo usage: xroff xfile [files]
else
	xfile=$1
	shift
	: test to see if xfile is readable
	if test -r ${xfile}
	then
		: run sed to do editing
		sed -f ${xfile} $*
	else
		: simply pass input through unprocessed
		cat $*
	fi
fi

So, i can now put xroff in my pipeline, for example

	xroff foo a b c | pic | tbl | eqn | troff -mm

if you simply want to get the cross reference file set up correctly,
you can use the -a option on troff, redirect the output to /dev/null,
and you are on your way.

If anybody wants to develop the appropriate -me and -ms macros for this to
work, I would be happy to hear from them.

--tim budd
department of computer science
oregon state university

ilan343@violet.berkeley.edu (09/13/88)

In article <6399@orstcs.CS.ORST.EDU> budd@mist.cs.orst.edu (Tim Budd) writes:
>Here is an idea that is so simple I wonder it isn't more widely used.
>(so simple in fact I'm sure I'm not the first one to discover it).
>
>We can use the .sy command in ditroff, and a trivial shell script,
>to make an arbitrary cross referencer.  This cross referencer can be used in 
>a pipe, just like tbl, eqn, pic, bib and the rest.  The system needs only
>two strings and three macros.
>
Is the .sy command implemented in all versions of ditroff?

It does't seem to work with the version I use in this BSD machine.