Word and auto-generated cross-references (Part 1 of 2)

[K Watkins <KWATKINS -at- QUICKPEN -dot- COM>]

Okay, I guess I was wrong.  If this discussion is off-topic, it's apparently
not very far off.  I have gotten a whole bunch of requests for the Word
field codes discussion, and some of them don't have Email addresses on them.
 So I am posting to the list the stuff I have so far.  I have to split this
into two messages, because my Email system neither sends files nor accepts
messages over a certain length.  This is part 1 of 2:

Glenda Jeffrey (jeffrey -at- hks -dot- com) writes:

>I'm curious how you folks deal with auto-generated cross references in
>very long documents. The problem is that, in order to guarantee that
>the cross references are properly generated, you have to print the
>entire document. In our case, that's a couple thousand pages.

I'm working successfully with these issues in Microsoft Word 6.0c, where you
can update all cross references in a document with a couple of keystrokes,
no printing required.  Word is, of course, notorious for handling very long
documents very poorly.  I was working with a 200-page Word file, full of
linked bitmaps, callouts, index markers, and cross references.  When it
managed to corrupt itself severely three times in as many weeks, I gave up
and split the thing apart...with many thanks to Bob Lord and Kris Olberg for
the techniques they provided (partially outlined below)!

The document now exists as a set of six files:  front matter, back matter,
and four body sections.  I use RD fields in the front and back files in
order to include the whole document in the contents and the index.  For
cross references within a body section, the ordinary REF and PAGEREF fields
work fine.  For each cross reference between files, I use:

 - a SET field in the file I want to point TO, located right next to the
   text I want to point to.  Example (with field codes showing):

          {SET Install "{PAGE}"}To install the widget,...

   If I were using text rather than page-number cross references, the only
   difference would be putting the desired text, rather than the {PAGE}
   field, between the quotes.

 - an INCLUDETEXT field in the file where I want the cross reference to
   appear.  Example:

                ...For installation instructions, see page
                {INCLUDETEXT c:\\docs\\firstfile.doc Install}.

It works smoothly, so long as I include the full pathname in the INCLUDETEXT
field, with double slashes.

I spent a bit of time figuring out how to insert SET and INCLUDETEXT fields
repeatedly with minimal keyboard/mouse action.  (For instance, if I just
copy, paste, and edit a SET field, Word seems unable to perceive the edit
accurately.)  Further details available on request.

Note on page numbering (new thread?)
======================
The one inconvenience, since my document has consecutive page numbering
throughout, is that I have to set the first page number of each file by
hand--and reset it whenever I get page tumble:  Check the number of the last
page in the front matter, set the first page number of the first body
section accordingly.  Check the number of the last page in the first body
section, set the first page number of the second...etc.

If you're using page-number cross references, as I am and Glenda isn't, you
need to be sure that pagination is current in the file containing the SET
field, before you update an INCLUDETEXT field.  Thus, in a document with
thousands of pages (and therefore dozens or hundreds of files), the task of
keeping the cross references accurate might become burdensome.

I have seen the suggestion that you can get around this by numbering pages
by chapter (page A-1, A-2, etc.).  That way you can let every file start
with page 1 and just include the first part of the page number in your
page-numering footers ("Page A-{PAGE}") and in your text ("see page
A-{INCLUDETEXT...").  However, numbering pages by chapter makes it a _lot_
more work to generate an index:  you have to auto-generate each chapter's
index separately, manually insert the "A-" for every page number in each
index, and then sort all the indexes together.  And if you have sub-entries
in your index, the automatic sort separates them from their main entries!

Anyone care to comment on other factors affecting the decision to number
consecutively or by chapters?  I have always preferred consecutive
numbering, at least when the whole thing really was intended as one unified
document, rather than a loose compendium of related materials.  It's a lot
easier to guess where to thumb to in order to find page 247, rather than
page F-38.

K Watkins
kwatkins -at- quickpen -dot- com
speaking for myself, not my employers
 From ??? -at- ??? Sun Jan 00 00:00:00 0000==
From Bob Lord:

On 11/1, K Watkins wrote:

re: cross refs in Word 6.0c:

"For each cross reference between files, I use:
<snip>
-an INCLUDETEXT field in the file where I want the cross reference to
appear.  Example:
        ...For installation instructions, see page
        {INCLUDETEXT c:\\docs\\firstfile.doc Install}.
It works smoothly, so long as I include the full pathname in the INCLUDETEXT
field, with double slashes."

>>>>>>>>Actually "K", I'd recommend using only the relative file path (i.e.
the file name only, with no path) unless you _really_ need to specify a
specific disk and subdirectory structure.  If you use the full path name,
your document won't be very portable.

I have a couple of 700-page books I've done in Word using these cross ref
techniques, and I used only the relative path in all instances.  I keep all
30 or so files for each book in the same directory, using filenames that
lend themselves to an orderly structure.

I can move all the files to any other machine or directory without changing
anything in the cross references or the directory structure, and the books
build with no changes.  Also, other writers can contribute to the book from
their own machines, with no portability problems.

Highly recommended, unless your document architecture is so large that the
files absolutely need to be in separate directories.

<snip>

Regards,

Bob

)))))))))))))))))))))))))))))))))))((((((((((((((((((((((((((((((((((((((((
Bob Lord
OEM Information Products                        "A very awed fellow!"
Digital Equipment Corporation
lord -at- ssdevo -dot- enet -dot- dec -dot- com
          office 719.548.6614  fax 719.548.2362
))))))))))))))(all opinions are mine and do not represent DEC)(((((((((((((