Cross-ref formats

[Combs, Richard]

Nancy Allison wrote: 
 
> I'm setting up a template and am trying to figure out a way to avoid having
> to create multiple x-refs to accommodate different punctuation. You know
> (x-ref is inside the underscores):
> 
> ---See __Appendix D, "Frying Pans and Toasters,"__  for more information.
> (X-ref includes comma inside quotation marks)
> 
> ---For more information, see __Appendix D, "Frying Pans and Toasters."__
> (X-ref includes period inside quotation marks)

Our template has xrefs for each of these. They look like this: 

	<Xref>Chapter\ <$chapnum>,<Default ¶ Font> \`<$paratext>,\'
	<Xref>Chapter\ <$chapnum>,<Default ¶ Font> \`<$paratext>.\'

I wouldn't mind a bit getting rid of the first. 

<snip> 
> If I create only one x-ref format, using only one kind of punctuation, most
> nimble tech writers will be able to construct nicely flowing sentences to
> employ it. Right?

Right. Assuming the writers are willing to follow a simple rule of sentence construction: always put the xref last: 

	For toaster specifications, see Appendix D, "Frying Pans and Toasters." 

To me, that's just good writing anyway, analogous to the way we write procedure steps: 

	To do X, select Framboozle.
 
> Or, I could decree that we never quote the titles of referenced sections,
> and omit any punctuation:
> 
> ---For more information, see __Appendix D__.
> 
> But I think that's a lousy solution: I don't want to omit a descriptive
> title just because it's a pain to set up the x-ref formats for it.

You could omit the chap/appendix number and just specify the title and page: 

	For more information, see "Frying Pans and Toasters" on page 67. 

The trailing punctuation isn't part of the xref. Here's the xref definition: 

	<Xref>\`<$paratext>\'<Default ¶ Font> on page\ <$pagenum>

Dispensing with quotes and using italics is another (although out-of-the-mainstream) option. But as William said, it seems to put the writer's needs first. If you go that route, do as Peter suggested, and create a char format specifically for that purpose. 

Regarding Art's suggestion of two templates, there may be workflows where that's necessary. But with WebWorks, Mif2Go, and (I'm pretty sure) RoboHelp, you don't change the book-oriented (chapter and page) xrefs in FM, you map them to online versions in the help tool. 

Finally, in crafting xref formats, don't forget some very simple ones (mostly just single  building blocks with a char format applied) that give you the flexibility to deal with unexpected needs. Here are some examples: 

<Xref><$paranum>
<Xref><$paranumonly>
<Xref><$paratext>
<Xref>page\ <$pagenum> 

HTH!
Richard


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------