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
------
_______________________________________________
You are currently subscribed to Framers as [email protected].
Send list messages to [email protected].
To unsubscribe send a blank email to
[email protected]
or visit
http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com
Send administrative questions to [email protected]. Visit
http://www.frameusers.com/ for more resources and info.
