Cross-ref formats

[Les Smalley]

I think you need to have at least formats for referring only to the numbered bit (e.g., Appendix D) as well as the entire title with number (e.g. Appendix D, "Frying Pans and Toasters.")

The biggest issue with the second format is if the text being cited includes punctuation itself.  

My preference would be to exclude terminal punctuation from the text and allow the writers to add it as needed in constructing their sentences including the references.  

I would also omit the quotation marks from the XRef formats and instead italicize (or bold) the text being cited (including the numbered prefixing info) to help it stand out from the surround paragraph and give your writers the maximum flexibility with a minimal number of formats to insert in their content.

– Les Smalley
 

--- On Tue, 8/4/09, Nancy Allison <maker at verizon.net> wrote:
Once more, this time with content!

For your technical manuals, what is your preferred set of cross-reference formats?

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)

---[Inspiration fails me, but I am sure there's a similar example that does not use any punctuation within the quotation marks]

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?  

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.

What is your solution?