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

[Bernard Aschwanden (Publishing Smarter)]

More good stuff. Thanks and keep it coming folks :)

-----Original Message-----
From: Steve Rickaby [mailto:srickaby at wordmongers.demon.co.uk] 
Sent: Friday, December 2, 2016 12:16 PM
To: bernard at publishingsmarter.com; framers at lists.frameusers.com
Subject: Re: [Framers] Cross reference format (what do you use?)

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