Posts Tagged ‘cross references’

h1

Word: Change author/date citations to links to auto-numbered references

May 1, 2019

Warning: Long post! Lots of steps, lots of concentration required. I suggest printing it out, grabbing a cup of your favourite beverage (preferably nonalcoholic), and working through it step by step with no distractions until you are familiar with the process.

Issue

For many years, my main client used author/date citations (e.g. Smith, 2006) in their documents, with an accompanying References list that was sorted alphabetically by author (followed by date if there was more than one instance of an author, and an alphabetic designator if there was more than one year the same by the same author).  Because ‘author’ includes any authoring body, there was a problem—they cite many of their own documents, which meant you had citations such as ‘Company, 2010’, ‘Company, 2010a’, ‘Company, 2010b’ etc. If you have to refer to more than 26 documents by the same author in the same year, you run out of letters!

To help alleviate this issue and streamline their references and citations, about three years ago they changed their templates to include an auto-numbered References list, which meant the author/date method had to change to use cross-referenced numbers. It’s a far more efficient method and is easy to update if items are added to or deleted from the References list.

For new documents, it’s easy—just use the new method. But what about the older documents on the old templates that still use the author/date citation method? If the decision is made to transfer an older document to the current template, then that decision invariably includes updating the author/date citations and references to the numbered method.

Below I discuss how I do this. It’s a complex method that can take many hours (some of the references lists I deal with contain 200 or more items). It would be greatly simplified if the client used something like a networked EndNote or Zotero database, but they don’t and won’t in the foreseeable future, so that’s not an option. In the meantime, I do it manually. This process works for me—it may not work for you, or you may use a better method. Feel free to comment.

Solution

This process assumes you’re working with an existing document that uses manually entered author/date citations, and have an existing references list that holds the bibliographic details for those citations.

Unless you are required to track these changes, turn off Track Changes before you start.

Step 1: Add a Back button to your Quick Access Toolbar (one-off task)

If you don’t already have a Back button on your Quick Access Toolbar (QAT), add it. You’ll thank me later!

  1. Click the drop-down arrow at the far right of the QAT, and select More Commands.
  2. In the Choose Commands From column, select All Commands from the drop-down list.
  3. Scroll down the list to Back and select it.
  4. Click Add in the middle of the two panels to add it to the QAT. Optional: Use the up and down arrows on the right to place it where you want it to go.
  5. Click OK.

The Back button is now on your QAT. It is inactive at the moment and only becomes available once you’ve clicked a cross-reference link (e.g. to a heading from the table of contents, or to a section, table, figure, appendix, or reference list number), and gone to another place in the document. You can then click it to return to where you clicked the link.

Step 2: Create a blank auto-numbered References list (one-off task)

You’ll already have a References section in your document—in this step, you can either create a new section, or add the new auto-numbered table to the existing one. You’ll still need to keep the existing list until you’ve transferred all the bibliographic details to the new list.

  1. Optional: Add a new heading (References) to your document, and assign the Heading 1 style to it. (If you want to keep your existing References section, just add a couple of empty paragraphs above or below the current list and then follow the steps below.)
  2. Insert a multi-row, two- or three-column table in this section, and style it as you want:
    • Use two columns if you only need a column for the number and another for the bibliographic details of the reference
    • Use three columns if you also need a column for document numbers or other information
    • Apply table header row styling to the top row, and add column headings (I use Ref. No., Title, and Doc ID).
  3. Select all the cells (but not the header row cell) in the first column and apply auto numbering to them:
    • Use either the number icon on the Home tab, or another style you use for numbering
    • Make sure the numbering starts at 1.
  4. Add more rows (I typically start with 25 rows, adding more as needed).

Step 3: Find and highlight all citations (one-off task)

In this step, you’ll use the power of wildcard find and replace to find all author/date citations, replace them with themselves (i.e. make no change), add a designation for the cross-reference (in this example, (Ref. ), which has a nonbreaking space between the period and the closing parenthesis), and highlight them. The pattern you’re looking for is a year (the authors [and how the citation is written] will be different, so you can’t pattern match those, but the years are likely to start with only ’19’ or ’20’). Whether the citation is styled ‘(Smith, 2006a)’ or ‘Smith (2006b) found…’, this method will still find it.

  1. Go to the beginning of the document.
  2. Select a highlight colour you’re not using for anything else. You MUST select a highlight colour—if you don’t, then no highlight colour will be applied to the found text.
  3. Press Ctrl+h to open the Find and Replace dialog.
  4. Click More.
  5. Check the Use wildcards checkbox.
  6. In the Find field, type: (<19*>)
  7. In the Replace field, type: \1 (Ref.^s) (Note: There’s a space after 1)
  8. With your cursor still in the Replace field, click Format and select Highlight. ‘Highlight’ should be shown immediately below the Replace field.
  9. Click Find Next.
  10. If you find a citation, click Replace to highlight the date and add the partial text container for the cross-reference number (i.e. (Ref. ) ). This method finds ALL words starting 19, including measurement values, dates, etc. whether they are part of a citation or not, so NEVER click Replace All. Check every one, and keep clicking Find Next for each date you find that isn’t part of a citation, only click Replace for those that are part of a citation. Ignore the dates in the References list—they aren’t citations either.
  11. Once you’ve finished the 19xx dates, it’s time to do the 20xx dates. Go back to the top of the document. In the Find field change 19 to 20, leaving everything else the same (you should now have (<20*>) in the Find field, and the Replace field should still be \1 (Ref.^s), with ‘Highlight’ listed below it).
  12. Click Find Next.
  13. If you find a citation, click Replace to highlight the date and add the partial text container for the cross-reference number. The same rules apply as listed in step 10 above.
  14. Once you’ve finished, close the Find and Replace dialog.

You’ve now identified all the citations in the document. The next major step is the most time-consuming, so make sure you allow plenty of time for it. For a long document with many different citations, this next step could take many hours.

Step 4: Assign a cross-referenced number to each citation (repeat multiple times, once for each citation)

  1. If field shading isn’t turned on, turn it on:
    • Go to File > Options
    • Click Advanced
    • Scroll down to the Show Document Content section
    • Select Always from the Field Shading drop-down list.
  2. Go to the beginning of the document.
  3. Use your eyes to scan the text for the highlight colour you used for the citations. If you didn’t use a different colour, it may not be a citation, so check.
  4. Leave the author/date as it is for now, and put your cursor just inside the closing parenthesis, after the nonbreaking space.
  5. On the References tab > Captions group, click Cross-reference.
  6. Choose:
    • Numbered item from the Reference Type drop-down list
    • Paragraph number (no context) from the Insert Reference To drop-down list
  7. Scroll down the list of items to the References section, then select 1. immediately below it. (This is the row numbered 1 in the References list table you created earlier.)
  8. Click Insert.
  9. A cross-reference field for 1. is added to your citation—you should now have (Ref. 1). Because you turned on field shading in step 1, the number should have grey shading behind it, indicating it’s a clickable field (you’ll see this only after you remove the highlighting).
  10. Copy the original author/date citation (e.g. Smith, 2006), then Ctrl+click the cross-reference number. This takes you to the matching row in the References table.
  11. Paste the copied author/date citation into that row. You’ll add all the bibliographic details later—you don’t want to lose the original citation at this stage, so you’ll store it in the row that will later be populated with the bibliographic details for that citation. (Tip: If you only have a small list, then you could find the matching details from the old list and add them now)
  12. Click the Back button you added earlier to the QAT to return to the citation cross-reference.
  13. Copy the number you just inserted (the field) to the clipboard.
  14. Because a single citation could have been used several times in the document, you now need to search for other instances of that citation and add the cross-reference you copied in the step above:
    • Open the Find and Replace dialog (Ctrl+h)
    • Clear the Use wildcards checkbox
    • Clear the text from the Find field
    • Clear the text from the Replace field
    • Click No Formatting to clear the ‘Highlight’ wording from below the Replace field
    • In the Find field, type the original author/date citation (sometimes the author or the date may be enough)
    • Click Find Next
  15. If you find the citation used again:
    • Click out of the Find and Replace dialog
    • Paste the field (the cross-reference number) you copied at step 13 into the (Ref. ) placeholder, just before the closing parenthesis
    • Clear any remaining highlighting and delete any unwanted text and/or extra parentheses for this citation, including the author/date part—you no longer need this because you already added it to the References list back in steps 10 and 11.
    • Click back into the Find and replace dialog, and continue searching for other instances of that citation
    • For each one found, paste the field (as above) and clear the highlighting, extra text etc.
  16. Once you’re satisfied that you’ve found them all, go back to the first instance of that cross-referenced citation, delete the original author/date, any extra parentheses, and clear the highlighting.
  17. Repeat steps 3 to 16 above for the second citation, choosing 2 instead of 1 at step 7.
  18. Repeat steps 3 to 16 for every other highlighted citation, changing the number each time. Yes, this can take HOURS. Add more rows to the bottom of References list if you’re starting to run out.

Step 5: Populate the References list with the bibliographic details from the old References list (one-off task)

Once you’ve added all the citations, you’ll need to find their matching counterparts in the original References list.

  1. Go to the first row of the table.
  2. Check the author/date citation you pasted there earlier.
  3. Find the matching item in the original References list. Use the original author/date citation information to confirm you have the correct one. (Hint: Copy the original References list into a new document and show it on a second monitor, if you have one.)
  4. Copy/paste the original bibliographic details into the Title cell in the matching row of the numbered table, deleting  the original author/date citation placeholder. (If you’re not comfortable deleting the original citation just yet, leave it for now and highlight it for later deletion.)
  5. Optional: Delete any date designator (e.g. 2010b becomes 2010), and shift any document number etc. to the other column.
  6. Repeat the steps above for each row of the table that has an author/date citation.
  7. Delete any unused rows when you’ve finished.

Adding, deleting items from the new list and updating the list

Adding new references and citations

If you need to add new items to the References list table, the simplest way is to:

  1. Insert a new row at the end of the table.
  2. Add the bibliographic details.
  3. Create the cross-referenced citation to that new number.

If you want to add the item so that the cross-referenced citation is numbered sequentially in the main body of the document, in line with the other citations, it’s a bit more complex:

  1. Turn off Track Changes.
  2. Insert a new row where you want to add the new reference (e.g. you might want it to become citation number 24, so you need to add a new row after row number 23. This new row becomes 24 and the previous 24 becomes 25 etc.). The numbers in the table update automatically, but the citations in the main document don’t.
  3. Add the bibliographic details.
  4. Create the cross-reference citation to that new number.
  5. Update all the fields in the document to reflect the new number order of the other cross-referenced citations (e.g. the previous number 24 now becomes number 25, 25 becomes 26 etc.). See below for how to do this.

Deleting reference items

If you need to delete reference items from the table:

  1. Turn off Track Changes if you aren’t required to track this change.
  2. Go to the cross-referenced citation if it exists (e.g. press Ctrl+f and search for Ref. 23 [you have to search via the navigation pane as you can’t search for a field number from the Find and Replace dialog]).
  3. Confirm that this is the one to be deleted—Ctrl+click the number to go to that row in the References table.
  4. If it’s correct, click the Back button on the QAT, and delete the cross-referenced citation.
  5. Search for any further instances of this and delete them too.
  6. Return to the References table and delete the row. The numbers in the table will automatically update, but the citations in the main document won’t.
  7. Update all the fields in the document to reflect the new number order of the other cross-referenced citations (e.g. the previous number 23 now becomes number 22, 24 becomes 23 etc.). See below for how to do this.

Updating the cross-referenced citations

Whenever you change an auto-numbered table, the numbers will automatically update, but the citations that refer to them don’t until you update all the fields in the document.

Unless you are required to track these changes, turn off Track Changes before you start.

To update all the fields in your document, do one of these:

  • switch to Print Preview view, then back to Print Layout view (quickest and easiest); or
  • press Ctrl+a to select the entire document, then press the F9 key; or
  • press Ctrl+a to select the entire document, then right-click on the selection and choose Update Field.

To update a single field, place your cursor to the immediate left of the grey shading, right-click, then select Update Field.

To check for broken fields, press Ctrl+f and search for Error!. If this message is in a cross-referenced citation, it means that Word can’t find the matching number in the References list. You’ll either have to add a new row for it (and reassign the correct number to the cross-reference), or delete the cross-referenced citation.

h1

Word: Cross-Reference Manager add-in: Review

August 26, 2016

Back in 2010, I wrote a blog post pleading with Microsoft to fix/enhance the cross-reference functionality in Word. Others commented on that post, offering their own suggestions and venting their frustrations with it as well.

Well, someone did see that post and has done something about it, though they aren’t from Microsoft. Lene Fredborg from DocTools (and a Microsoft Word MVP) has written a Cross-reference Manager (CRM) add-in to Word that addresses all my woes, and more. It costs just under US$50 per license for 1 to 4 licenses, and the price per license goes down the more licenses you buy.

Several months ago, Lene asked me to beta test the add-in and make suggestions. Anyone who’s done beta testing knows that process takes longer than expected with the to-ing and fro-ing over time. My tests were done on a 200+ page, 73,000-word document that had more than 350 cross-references, so I really put it through its paces! Lene released the final version in July.

In the interests of transparency, yes, because of my contribution via beta testing I have a free license for my copy of the add-in, but I was not asked to do this review, nor do I receive any financial benefit from it. My aim is to let my readers know that it exists and to test it out for themselves (there’s a 15-day free trial period).

So, on to the review…

Who is the add-in for?

This add-in is for anyone using Microsoft Word on a PC (NOT Mac or tablet versions), from Word 2007 onwards. For those of us who work with long complex Word documents where we use automated caption numbering, outline heading numbering, and the like, and need to insert multiple automated cross-references (to tables, figures, sections, appendices, references etc.) into our documents, CRM is a major improvement on Microsoft’s Cross-reference dialog box.

However, if you don’t use cross-references, or only do a few per document, CRM is probably not for you.

What happens to my ribbon?

Once installed, CRM doesn’t replace the in-built Cross-reference dialog box; instead, it lives on a new DocTools tab (Manage Cross-references group) on the ribbon. You can use whichever you prefer — you aren’t forced to use one or the other.

You can add the functions on the DocTools ribbon to the Quick Access Toolbar by right-clicking on the function and selecting Add to Quick Access Toolbar.

Note: DocTools makes other Word add-ins, which get added to the same ribbon but in different groups.

What does it do?

CRM adds a huge amount of functionality to cross-referencing in Word. Essentially, it’s cross-referencing on steroids! It addresses most (all?) of the issues I raised in that post from 2010, and issues raised in several of the comments on that post, as well as other issues that frustrated Lene.

There are three icons in the Manage Cross-references group of the DocTools tab:

  • Insert Cross-references:
    • Use this instead of the standard Microsoft dialog box.
    • Has a filter function to just show items with the character you type (e.g. type ‘3’ to see all Headings with a ‘3’ in their outline numbering, such as 2.3, 2.13, 3.1, 3.2, etc.)
    • Can resize the dialog box and increase the number of items displayed at once.
    • Can set your cross-reference defaults from this screen (as well as via Tools).
    • Target types don’t separate Figures, Tables, Equations — the more sensible Captions is used, and then you select the type of caption.
    • Your most recent settings are retained for the next cross-reference you add.
  • Cross-reference Tools:
    • All sorts of functions to identify and fix broken cross-references. (Note: Any highlighting you add/remove via the tools will NOT change any existing highlighting you’ve added to the document for other purposes.)
    • Set defaults for the Insert Cross-references dialog box.
    • Set custom text to go in front of a cross-reference (e.g. ‘See Section’ xx.xx; ‘Refer to’ Table xx-xx; etc.)
    • Update all fields.
    • Toggle display settings for field shading, bookmarks etc. (much quicker than doing it via Word’s Options dialog box)
    • And many many more…. (see the More Details tab on the webpage for CRM for full descriptions of all functions, screenshots etc.: http://www.wordaddins.com/products/cross-references-word_doctools-crossreferencemanager/)
  • Help: Lene has written a very comprehensive Help file to go with CRM. Read it to see all the things CRM can do — I only skim over the main functions in this review.

Summary

This is a terrific add-in that improves on Microsoft’s own cross-referencing function, and makes it much easier to assign cross-references. It’s a great tool for all power Word users.

I highly recommend it.

h1

Word: Assigning automated cross-references

August 8, 2014

Based on a Writing Tip I wrote for my work colleagues. Warning: LONG! as there are different instructions for each type of cross-reference.

****************

In many of the Word documents you write, you may need to refer the reader to another section, an appendix, a table, or a figure, or numbered reference in a References list. You do this with a cross-reference (e.g. ‘see Table 5-2’). Although you can just type the cross-reference (x-ref), if you add more sections/tables/figures etc. or delete some, then some or all of your typed x-refs will be incorrect and take the reader to the wrong place.

The solution is to use automated x-refs.

That way, when you add/move/delete sections/tables/figures etc., you just need to update the fields in your document to automatically update the x-ref numbers to reflect the new numbering of these elements. The other advantage of automated x-refs is that they are clickable in the Word document (Ctrl+click) and sometimes in PDFs (depending on the Acrobat settings) – in both cases, clicking the link will take you straight to the place referred to.

Assumptions: All the instructions below assume you are working in a document that is based on a template that uses:

The instructions vary a little for each type of cross-reference—figure/table, section, appendix, numbered References list item. However, for each you will start with the References tab > Captions group > Cross-reference button:

x-ref_refs_tab

 

Insert an automated cross-reference to a figure or table

  1. Place your cursor in the text where you want to insert the cross-reference.
  2. Go to the References tab > Captions group, then click Cross-reference.
  3. In the Reference type field, click the drop-down arrow and select either Figure or Table (they’re at the bottom of the list).
  4. In the Insert reference to field, click the drop-down arrow and select Only label and number.
  5. Select the figure or table from the list in the lower half of the dialog box.
  6. Click Insert.

x-ref_fig-table

Insert an automated cross-reference to a section

  1. Place your cursor in the text where you want to insert the cross-reference.
  2. Type the word ‘Section’ and a space.
  3. Go to the References tab > Captions group, then click Cross-reference.
  4. In the Reference type field, click the drop-down arrow and select Heading.
  5. In the Insert reference to field, click the drop-down arrow and select Heading number (no context).
  6. Select the section from the list in the lower half of the dialog box. Hint: If it’s a long list, type the main section number – e.g. type 8 to take you straight to headings starting with ‘8’.
  7. Click Insert.

x-ref_section

 

Insert an automated cross-reference to an appendix

  1. Place your cursor in the text where you want to insert the cross-reference.
  2. Go to the References tab > Captions group, then click Cross-reference.
  3. In the Reference type field, click the drop-down arrow and select Numbered item (first in the list).
  4. In the Insert reference to field, click the drop-down arrow and select Paragraph number (no context).
  5. Select the appendix from the list in the lower half of the dialog box. Hint: Appendices are always listed at the END of the list, so you might have to scroll down a long way.
  6. Click Insert.

x-ref_appendix

 

Insert an automated cross-reference to an auto-numbered Reference list item in a citation

  1. Go to the References section, note its section number (e.g. 9.0), then identify the row number in the References list for the document you want to cite (e.g. row number 23).
  2. Place your cursor in the text where you want to insert the cross-reference.
  3. Type ‘(Ref. )’; make sure you add a non-breaking space (Ctrl+Shift+spacebar) after the full stop, then put your cursor after the space and before the closing parenthesis.
  4. Go to the References tab > Captions group, then click Cross-reference.
  5. In the Reference type field, click the drop-down arrow and select Numbered item (first in the list).
  6. In the Insert reference to field, click the drop-down arrow and select Paragraph number (no context).
  7. Go to the References section (e.g. 9.0)  in the lower half of the dialog box.
  8. Scroll down the list of numbers after the section number/heading and select the number of the row you identified in Step 1.
  9. Click Insert.

x-ref_citation

What happens to the x-ref numbers if I’ve added new tables/figures/sections etc.? How do I update them?

When you add a new section, table/figure, appendix etc. Word automatically applies the correct sequential number for where you’ve placed it. If you move an existing section or appendix, these heading numbers will change automatically too. But tables and figures and all the x-refs DON’T change their numbers until you update all the fields in your document.

Although there are several ways to update all the fields (and therefore the automated numbers), the quickest, simplest, and most foolproof way is to switch to Print Preview mode, then switch back—almost all your numbers automatically update:

  1. IMPORTANT: Make sure Track Changes is turned OFF. Weird things happen if track changes is on, including possibly losing your x-refs!
  2. Go to File > Print. The print preview of your document shows on the right.
  3. Go back to the Home All your fields are updated automatically.

That’s it!

However, this method doesn’t update your table of contents, list of tables, list of figures, etc.—you have to do those separately using the applicable Update Table buttons on the References tab, or use the method below.

To update EVERYTHING in your document at once:

  1. IMPORTANT: Make sure Track Changes is turned OFF.
  2. Select the entire document (Ctrl+A).
  3. Right-click on the selection and select Update Field.
  4. When asked about updating the table of contents etc. select Update entire table and click OK. You may have to answer this several times for each contents list.
  5. Repeat steps 3 and 4 once more to be sure you got everything. Sometimes, the first update will update the numbers for moved figures/tables etc. but not the x-refs too—to be certain you update the x-refs, repeat these steps a second time.

 

TROUBLESHOOTING

What does ‘Error! Reference not found.’ mean?

You’ll get ‘Error! Reference not found.’ for any x-refs that have nothing to point (refer) to. The most common reason for these error messages is that you’ve deleted a section heading (or a figure/table caption) without realizing that there was a x-ref to it somewhere else in the document. Behind the scenes, Word has unique ID numbers for each x-ref that refers to specific sections, tables, etc. So if you delete the section heading/caption but not the x-ref, Word loses the connection between the two when the fields are updated, and so reports ‘Error! Reference not found.’. The only simple solutions are to:

  • delete the message if the table etc. has been deleted, OR
  • replace the message by creating a new x-ref to the correct place.

What about Section 0?

If you notice some ‘Section 0’ x-refs after you update the fields, there’s a good chance you inserted a new paragraph by pressing Enter at the beginning of an existing section heading and then changed the style of the new paragraph. This screws up the internal IDs. Best practice is to insert a new paragraph at the END of the previous paragraph by pressing Enter. For detailed information on this problem and various methods of solving it, see: http://www.thedoctools.com/demos/demo_crossref_2.html

**********************

See also:

[Links last checked August 2014]

h1

Word: Updating automated caption and cross-reference numbering

January 31, 2014

NOTE: You must be using automated caption numbering, Word’s heading styles (mostly), and automated cross-references (x-refs) for these steps to work.

If you have a document with several sections and automated table/figure captions and x-refs to these, you might wonder how you can update these numbers etc. to reflect any changes you make, such as inserting new tables/figures/sections, or moving existing ones to other places in the document, or deleting some of them.

It’s actually very easy to do, so here’s how:

  1. Turn off Track Changes if they are on.
  2. Press Ctrl+A to select the entire document.
  3. Right-click on the selection, and select Update Field. (This update can take several minutes on a very long or complex doc with lots of x-refs, so be patient…. You’ll see the ‘spinning wheel of death’ and possibly ‘Not Responding’ in the title bar while Word is updating your doc, so don’t touch the mouse or keyboard until the cursor turns back to a static arrow.)
  4. Repeat steps 2 and 3. (Why? Because the first update seems to update the numbering and captions, and the second pass seems to updates the x-refs. Sometimes just a single pass will work, but I’ve had situations where I’ve needed to do the update a second time, so now I just do it twice anyway.)

Once you’ve updated the caption numbering and the x-refs, you may need to update the automated Table of Contents (TOC), List of Tables (LOT), and List of Figures (LOF) too. Sometimes these elements update as part of the steps above, but not always.

  1. Make sure Track Changes is still off.
  2. Click anywhere inside the TOC.
  3. Go to the References tab (#1 in the image below), Table of Contents group on the ribbon (far left), then click Update Table (#2 in the image below). If asked, select the option to Update entire table.
  4. Click anywhere inside the LOT.
  5. Go to the References tab, Captions group on the ribbon (middle), then click Update Table (#3 in the image below). If asked, select the option to Update entire table.
  6. Click anywhere inside the LOF.
  7. Go to the References tab, Captions group on the ribbon (middle), then click Update Table (#3 in the image below). If asked, select the option to Update entire table.

TOC_update

[based on a Writing Tip I wrote for my work colleagues]

h1

Cross-references

October 15, 2012

One of my colleagues asked me some questions about cross-references.

But first, a bit of backstory…

We’re preparing a very large Word document (800+ pages) and each Section (about 18 of them) is being prepared by a different author. At some point, I will have the job of bringing these individual Sections (aka chapters) together into one BIG Word document prior to it going out to the printer and prior to it being PDF’ed and put online for public distribution and comment. I’ve designed the Word template and the styles to make this job easier; I’ve tested the process of compiling the document’s Sections; and I’ve documented the ‘gotchas’ I’ll have to watch out for.

In the meantime, the authors have been beavering away on their Sections. One of the ‘best practice’ things they’ve been doing is inserting automated cross-references for tables, figures and subsections WITHIN their Section, and inserting plain text Section/subsection/table/figure numbers and captions/headings for what will eventually be automated cross-references to other Sections once the document is a single document. It will be my job to create the automated intra-Section cross-references.

But there must have been some discussion in the office about the number of these cross-references to other Sections — perhaps authors were finding it cumbersome to add them, perhaps they were concerned about the readability of the document when it was peppered with cross-references within the text. Maybe something else. So my colleague contacted me to get my advice.

Here’s a summary of my response:

  • Consider WHY you have a cross-reference (x-ref) to another section, table etc., whether it’s to something in the same Section or in a different one. The bottom line is that x-refs to a Section/subsection help you avoid repeating the same information in multiple places, or refer to a table/figure that follows or has gone before that provides the information the reader needs to make sense of the narrative.
  • Consider HOW a reader will approach a x-ref. In print, they have to flick the pages to find the supporting information, but in online (PDF) they only need to click the link to go to the relevant part to read the information, then can click back to return to where they were. Clicking a link is a simple process for the reader, though going back in a PDF is not quite as straightforward. (See my blog post about this from 2010: https://cybertext.wordpress.com/2010/07/06/acrobat-back-and-forward-buttons/)
  • Consider WHEN to insert a x-ref or not. If the reader MUST know about something that’s gone before or is to come (e.g. Section 8 Assessment Method) to properly inform the current section, then a x-ref is necessary. Likewise, if the data that supports a claim is held in a table or figure, then a x-ref to that table/figure is necessary. However, if the x-ref is a ‘nice to have’ and just offers a link to related (but not essential) information for the reader, then the author has to decide whether to include it or not.
  • Consider WHERE to insert a x-ref. Essential x-refs to other Sections and to tables/figures should go as close as possible to where the referring information is written (which is what you do now). However, for the ‘nice to have’ related x-refs that aren’t essential, consider whether breaking them out into a sidebar/box/list at the bottom of the Section/subsection might be more useful to the reader than peppering them throughout the narrative. If you do pursue this option, make sure the [government regulators] are happy with the idea first and that there’s nothing in the requirements documentation that prevents you from doing so. Also, I suggest you test it on a single Section to see how easy/hard it is to do and how convenient/awkward it is for a reader to deal with.
  • Consider WHO will read the document and HOW they will read it. Some readers of the doc will only focus on one or two Sections (e.g. the Department of Fisheries might only focus on marine Sections and ignore terrestrial fauna sections), while others may read the entire document. For a reader who has a limited focus, you cannot assume that because they are reading Section 9 that they’ve read the preceding Sections 1 to 8; even for readers who read the entire document, you can’t assume that they’ve read and remembered what was said in earlier Sections.
  • Please DO NOT consider converting the existing automated x-refs into manual ones. There be dragons… Future updates to the documents (e.g. insert/delete a subsection, table/figure) would mean that existing references to subsection numbers, table/figure numbers would be out of order and it would be a nightmare to try to find and fix them all. Automated x-refs mean that you can add/delete material without upsetting the links.

Ultimately, knowing who the likely reader is for this document and how they will access the document will dictate the direction my colleague will take. After all, such a document is about the reader, not the writer, so whatever is easiest for the reader to deal with should prevail over any ‘it’s too hard’ issues that the authors may have.

See also:

[Links last checked October 2012]

h1

Word: Sometimes a List of Tables/Figures just won’t update

March 28, 2012

I’ve had several documents recently where the List of Tables and/or List of Figures just won’t update to list all tables/figures in the document.

The captions are all applied correctly, and I’ve tried the various methods for updating the fields. I’ve even reinserted the List of Tables/Figures — all to no avail. Some tables/figures just don’t show in the lists.

I’ve suspected it was to do with track changes being on in the document, even though none of the captions or the paragraphs surrounding them were the subject of tracked changes. And I also suspected that something was happening with the field updating that can get messed up when track changes are on (see https://cybertext.wordpress.com/2009/10/16/word-macro-to-fix-track-changescross-references-issues/ for how to fix that).

To confirm my suspicions, I copied a document that wouldn’t behave and put it into a testing area (so I wouldn’t mess up the original). I then accepted all track changes in the document and updated the List of Tables. It worked! All the tables that should have been listed originally were now listed correctly.

The problem is that the authors need to keep on track changes so that the regulators can see what’s changed in these docs, so they have three choices:

  • Accept all track changes (NOT an option for these docs)
  • Ignore the pesky List of Tables and hope that the reader doesn’t notice ;-)
  • Ignore the pesky List of Tables and make a note to the regulators that it will update correctly once all track changes are dealt with.

[Links last checked March 2012]

h1

Message to Microsoft: Fix Word’s cross-reference dialog box. Please.

August 16, 2010

I use Microsoft Word — a lot. I’ve been using Word since the heady days of Word 2.0, and I’ve been using Word 2003 and more recently Word 2007 day in/day out for the past two years on my current contract. I’ve been getting up close and personal with Word, as evidenced by the number of blog posts I’ve written on Word’s idiosyncrasies. While there have been many improvements in Word 2007, there are areas that still have a way to go.

Most of the documents I’ve been working on for the past two years are long scientific reports — a single document can have hundreds of cross-references to figures, tables, plates, sections, appendices etc.

As a result I’ve opened the Cross-reference dialog box more times than I can count. And that dialog box alone sucks as far as usability is concerned (‘sucks’ is a technical term!). While there have been some improvements to this dialog box in Word 2007, there’s a lot about this dialog box that just doesn’t work efficiently. (NOTE: I have not used Word 2010 yet, so these comments are about Word 2007. I’d appreciate it if someone using Word 2010 can report if any of these issues have been fixed.)

So, if you’re listening Microsoft, here are 10 productivity improvements I’d like to see made to this dialog box (numbers are used for reference only — they do not imply priority or sequential order):

Update August 2016: There’s now an add-in for Word for PCs that solves most (all?) of these issues. See https://cybertext.wordpress.com/2016/08/26/word-cross-reference-manager-add-in-review/

  1. Remember dialog box resizing. In Word 2007, this dialog box is resizable (yay!). But don’t get too excited… When you close the dialog, the size you’ve dragged it to is not ‘remembered’, so as soon as you re-open the dialog, it’s back to its default size and you have to resize it again. This gets ‘old’ very quickly. Yes, I know I can keep the dialog box open while I’m doing other things in the document, but sometimes I need the screen real estate and so I’ll close it only to re-open it again a few minutes later, and have to resize it again.
  2. Resize the drop-down selection lists to fit the available selections. The current situation is just bad design, in my opinion. Even the default Reference type list includes more selections than are visible in the drop-down list. And if you’ve added more (e.g. Plate, Equation, Photograph), then the list is even longer. But someone, somewhere at Microsoft decided that this drop-down list would only ever display 6 items! Which means if you have a list longer than that, you have to scroll. Oh, and for bonus points, someone at Microsoft decided not to list these selection options in alphabetical order!
  3. Increase the number of items displayed by default. The default size of the dialog box only displays 12 items in the list of available headings, figures, tables etc. Long documents can easily have hundreds of headings. If there are only a few items in a particular document, then keep the default at 12, but if there are many more than 12, make the default something like 30 items. Surely a simple if/then statement in the code could make this possible? Of course, if Word remembered the dimensions of my resized dialog box (see item 1 above), this point about the default number would become moot.
  4. Give me the option to expand/collapse headings. As mentioned in item 3 above, a long document can have hundreds of headings. Some documents I’ve worked on have 30+ subheadings (at various levels) within a major heading. If I need to set a ‘heading’ cross-reference to section 8.2.3.5, then I really don’t want to scroll through every heading in sections 1, 2, 3, 4, 5, 6, and 7 as I do now. Yes, I know I can type the first character of the heading I want and skip to the beginning of that section quickly (e.g. type 8 to go to the 8.x headings if using an outline numbered list), but I still have to scroll to get further down to section 8.2.3.5. If this list had expand/collapse functionality, then I could collapse all headings I didn’t want to see and just expand the section I was cross-referencing. Of course, ‘collapse all’/’expand all’ options should be available too. By the way, typing the first character only works effectively in the Heading and Numbered Item lists; however, if your table and figure lists start with the words Table or Figure, then typing a number or letter does nothing, and you have to scroll.
  5. Hide Reference Types not used in the document. This one is related to item 2 above. The documents I’ve been working on don’t use footnotes or endnotes, yet these are listed in the Reference type list. Why? If the document doesn’t use them, then they shouldn’t be available for selection. If I want to reference something in another document, then I can’t do it via this dialog box anyway.
  6. Remember my ‘Insert reference to’ preference for each Reference Type. This one is REALLY annoying. Because I switch between inserting cross-references to figures, tables, sections etc. within a section of text, I’d like Word to remember my Insert reference to preference FOR EACH TYPE while I’m in the current session. It can forget my preferences after I close Word, but while I’m working I’d like it to remember each insert preference for each Reference Type. Let me give you an example of how it works now:
    1. I select Table as my Reference type, then Heading number (no context) as my Insert preference, then I select the table.
    2. Let’s say the next item I have to insert a cross-reference to is another table. I can leave the dialog open, select another table and the Heading number (no context) selection also applied. So far, so good.
    3. The next cross-reference is a Figure, so I select Figure as my Reference type, then Heading number (no context) as my Insert preference, then I select the figure.
    4. Now I have to cross-reference another table. You’d think that Word would remember my previous table insert preference, but it doesn’t. I have to select Table and Heading number (no context) as my Insert preference AGAIN.
    5. And if the next one is a figure, I have to repeat that.
    6. Repeat for all the other Reference type/insert combinations. With potentially hundreds of cross-references in a single document, and hundreds of documents, this one gets old real fast.
  7. Let me set default Reference type/Insert combinations. Perhaps a better option than ‘remembering’ my most recently used Reference Type/Insert combination (see item 6 above) would be a setting where I could set my default Insert preferences for each Reference Type — that way, I could set it up once and not have to bother with it again. I’d still have the option for changing the insert options for an individual cross-reference, but the defaults would apply otherwise. This setting could go under Word Options > Display settings, or Word Options > Advanced where everything else seems to get dumped. Update for Word 2013: This aspect has been improved a little — when you set, say Table > Only label and number, then close the dialog, when you reopen it in the same document or another document in the same Word session (yes, even a new document created after you set that x-ref combination), that setting holds the next time you open the dialog box.
  8. Provide an option to list Level 1 paragraph styles in the Heading list. My client uses a special style for Appendix headings. This style has its Outline Level paragraph setting set to Level 1 so that it gets picked up and displayed in the automatic Table of Contents. However, these appendices do not use a standard Heading 1 to 9 style so are not listed in the Reference Type list for Heading — to find the appendices, I have to select Numbered Item and scroll to the bottom of that list. The writers on my team are scientists, not Word experts — they invariably cannot find the appendices when inserting cross-references, so they have to ask me to fix them.
  9. Let me assign ‘preserve formatting’ to the inserted cross-reference field from within this dialog box. Occasionally, and for no reason I can discover, the ‘preserve formatting’ option for an inserted cross-reference field goes missing. I don’t know whether it’s on insertion or something that an author does with it later (which is hard to believe as most of the authors I’m dealing with have no clue that these are fields, let alone how to fiddle with them). So a check box on this dialog to ‘preserve formatting’ might be useful as long as it didn’t mess up anything else with these fields (like become a toggle switch).
  10. Provide a double-click option to insert the cross-reference. When I find the correct table, figure, section cross-reference etc. to insert, I have to select it from the list, then click Insert; or select it then press the Tab key to go to the Insert button, then press Enter; or select it and press Enter. Another option I’d like for inserting a cross-reference is the ability to double-click the selection. With the existing options, you have to select the item (usually with the mouse), then do another one or two different actions (press a key, move and click the mouse) before you get the selection inserted. With a double-click option, double-clicking a selection would save mouse movements and prevent you having to switch from mouse to keyboard etc.

As I mentioned in my earlier blog post about the annoyances on this dialog box, these things would probably not bother someone doing the occasional insertion of a cross-reference. But for writers and editors working with long documents, reports, proposals, etc. who have to insert many cross-references, streamlining the functions of this dialog box would save many mouse movements and a LOT of frustration.

Does anyone know how to make suggestions to Microsoft? There used to be a ‘wish list’ address that was monitored, but I no longer know what that email or web address is, nor whether suggestions such as those above even get considered. If you know how to contact Microsoft, please comment below.

Update Nov 2013: Some information on merging cross-references, such as ‘Tables 4 to 8’ instead of ‘Table 4 to Table 8’:

Update September 2015: Five years and at least two versions of Word later and most of these issues remain… And there’s another one — if you have track changes on and delete the first character of a heading, then that heading isn’t shown in the list of Headings in the Cross Reference dialog box. It’s still listed in the Numbered Headings list, but that’s only applicable if you use outline numbered headings. See this post for the circumstances under which this occurs, and some workarounds: https://cybertext.wordpress.com/2015/09/16/word-cross-reference-dialog-box-doesnt-show-some-headings/

[Links last checked September 2015]