[Framers] Cross reference format (what do you use?)

[Steve Rickaby]

Hi Bernard

>I don't know. There are a LOT of ways to xref to stuff though.

Sure are. Quite often dictated by some sort of style guide, or an existing template. What follows are only my personal preferences.

>My question is this: What would be the top 3 or 4 ways *you* xref something?
>Not the steps to insert an xref, but the way it looks in your output.

Given the choice, 'This is shown in Figure 12', where only 'Figure 12' is the xref. Avoid unnecessary words: less is more. So in this case the xref would I guess be 'Figure <$paranum>'. In my opinion the more words you put into an zref format, the more inflexible it becomes.

>Do you put in full sentence xrefs?

I'm not sure whether you mean an xref containing a full sentence in the xref format (in which case, not if I can help it), or a <$paratext> xref to a sentence somewhere else in the document. I've used the latter case to ensure that a key text block is written once and cited by xref to ensure that it is identical wherever it occurs. I found it tedious to use variables for this, but I have forgotten why - probably the inability to inset character formats within variables.

>Do you use words in them?

The minimum, and only if absolutely necessary: I prefer to avoid more than one word. However, an exception would be if you want to repurpose the content for print and online by (amongst other things) switching templates, and you want to have words (for example, 'See page <>') for print, but not for online. Single-sourcing means that xref formats needs a lot more thought.

As an aside, publishers of textbooks destined for both print and eBook were keen to ensure that *every* object in a document had an xref to it. This makes sense, as an unreferenced object often (always?) cannot be found in eBook format. We had to include this in our editorial checks, but it sometimes resulted in a bit of a deluge of xrefs that didn't entirely make sense in the context of the body text. Superfluous xrefs are an irritant.

> Do you use quotes around content?

Definitely not, looks old-fashioned imho: much better to use a distinctive font or text face to make it clear that it's an xref.

This is just my 10c. Ultimately it all depends on the context. As Fred has pointed out, the situations are different in documents that haves numbered headings. If you want more info I can look back through past books and list some actual xref formats for you if that would help. In many cases I inherited templates that contained xrefs like 'For more information, see Section "<$paratext>" on page <$pagenum>'. I found these very cumbersome and usually reformatted them.

-- 
Steve