Re: Cross-ref formats
On Wed, 5 Aug 2009 11:23:06 -0400, Art Campbell art.campb...@gmail.com wrote: I believe an option within MIF2Go allows you to automagically impose a template of your choice on a book, so the conversion between multiple output types is transparent. Haven't played with it in a while, though, but I think it's still there... Yes, it is. It applies the templates just for that conversion, not permanently. It does this automagic g by saving the .fm file (if it has been edited) first, then applying the template, saving as MIF, and finally closing the original .fm file without saving to discard the template changes from it. Mif2Go then proceeds with the conversion using the MIF. So you never forget to apply a template. ;-) It also does updates and generates the book before conversions, if you set it to. Those changes *do* persist. HTH! -- Jeremy H. Griffith, at Omni Systems Inc. jer...@omsys.com http://www.omsys.com/ ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Cross-ref formats
Hi, all. I should have specified that my Framemaker template will be used to produce both PDFs and compiled help files. After a discussion on techwr-l or possibly this list, I decided to keep figure and table numbers in my online cross-references, but not page numbers. I currently append "online" to the names of x-refs intended for use online. I wouldn't want to get into separate templates for PDF and .chm output; too much hassle. I use conditional text in the Framemaker source files to use separate x-ref formats for PDF and .chm. Thanks for all the discussion and suggestions. I'm keeping the quotation-marks-versus-italics distinction for my PDFs (including the associated formatting hassles), but online it's a different story. In all cases, simpler is better! When I'm done, if anyone would like a copy of the template, I would be happy to send it on. --Nancy
Cross-ref formats
I use bold for referencing sections, instead of quotation marks. It makes things much simpler as far where to put the comma, and this style seems to be popular. -- Regards, Shmuel Wolfson Technical Writer 052-763-7133 Nancy Allison 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? > > ___ > > > You are currently subscribed to Framers as shmuelw1 at gmail.com. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/shmuelw1%40gmail.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. >
Cross-ref formats
I believe an option within MIF2Go allows you to automagically impose a template of your choice on a book, so the conversion between multiple output types is transparent. Haven't played with it in a while, though, but I think it's still there... Art Art Campbell art.campbell at gmail.com "... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl." -- Richard Thompson No disclaimers apply. DoD 358 On Wed, Aug 5, 2009 at 9:01 AM, Nancy Allison wrote: > Hi, all. > > I should have specified that my Framemaker template will be used to produce > both PDFs and compiled help files. > > After a discussion on techwr-l or possibly this list, I ?decided to keep > figure and table numbers in my online cross-references, ?but not page > numbers. I currently append "online" to the names of x-refs intended for use > online. > > I wouldn't want to get into separate templates for PDF and .chm output; too > much hassle. I use conditional text in the Framemaker source files to use > separate x-ref formats for PDF and .chm. > > Thanks for all the discussion and suggestions. I'm keeping the > quotation-marks-versus-italics distinction for my PDFs (including the > associated formatting hassles), but online it's a different story. In all > cases, simpler is better! > > When I'm done, if anyone would like a copy of the template, I would be happy > to send it on. > > --Nancy > > ___ > > > You are currently subscribed to Framers as art.campbell at gmail.com. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. >
Cross-ref formats
On Wed, 5 Aug 2009 11:23:06 -0400, Art Campbell wrote: >I believe an option within MIF2Go allows you to automagically impose a >template of your choice on a book, so the conversion between multiple >output types is transparent. Haven't played with it in a while, >though, but I think it's still there... Yes, it is. It applies the templates just for that conversion, not permanently. It does this "automagic" by saving the .fm file (if it has been edited) first, then applying the template, saving as MIF, and finally closing the original .fm file without saving to discard the template changes from it. Mif2Go then proceeds with the conversion using the MIF. So you never forget to apply a template. ;-) It also does updates and generates the book before conversions, if you set it to. Those changes *do* persist. HTH! -- Jeremy H. Griffith, at Omni Systems Inc. http://www.omsys.com/
Cross-ref formats
___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Cross-ref formats
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? ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Cross-ref formats
First, figure out your standard cross-reference style. See Appendix D See Appendix D, Frying Pans and Toasters, See Appendix D, Frying Pans and Toasters, on p. 247 See Frying Pans and Toasters on p. 247 Whatever it's going to be, standardize as much as you can. Think about whether the style you select works with headed paragraphs as well as chapters/appendices. Do your paragraphs have heading numbers? Should these be included in the cross-reference definitions? Bust out your Chicago Manual and choose wisely, Luke. Concerning the punctuation inside the terminal quote, you can either pick a style that moots it (any of the above examples, except the second) or you add two styles, one for commas, another for periods. In a template I built, I called these xref tags +p and +c (for an added period or comma) styles, e.g. ChapterXref+p. In the second example above, you could dispense with the +c xref definition, because the title is an appositive and must be offset with commas, but you would still need a +p to bring it on home. --William Nancy Allison 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? ___ You are currently subscribed to Framers as will...@inch.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/william%40inch.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Cross-ref formats
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 ma...@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? ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Cross-ref formats
On Tue, 04 Aug 2009 13:33:19 -0500 (CDT), Nancy Allison ma...@verizon.net 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. . . . What is your solution? Simple; I follow International English (UK) usage, and keep the punctuation *outside* the quotes: ---See Appendix D, Frying Pans and Toasters, for more information. ---For more information, see Appendix D, Frying Pans and Toasters. Most of the world, including those in the US, won't even notice. And it is more logical; the punctuation is *not*, after all, part of the quoted information. Consider: ---I don't know why she said No! ---I don't know why she said No! The meaning is different. In the first case, the speaker exclaimed. In the second, the narrator is exclaiming instead. Use the one that describes the situation more accurately. I'd even revise the first one so as to remove all doubt, as: ---I don't know why she said No!. which makes it clear that the speaker, not the narrator, was doing the exclaiming. HTH! -- Jeremy H. Griffith, at Omni Systems Inc. jer...@omsys.com http://www.omsys.com/ ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Cross-ref formats
On Tue, Aug 4, 2009 at 1:55 PM, Les Smalleyl_c_smal...@yahoo.com wrote: 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 As usual, Les has hit the nail! It's a good solution unless your style guide is iron-clad in its support of the common usage of enclosing quoted material in double quotes. Although these citations are quotes, they are also source names; it's common to use italics or other emphasis property to identify source names, such as these heading titles. I'd add the suggestion that you create a uniquely-named character format, for example, head_cite, that applies only the unique text properties to the referenced material; this makes it easy to modify the appearance, if necessary, without affecting Emphasis, bold or other defined character formats. HTH Regards, Peter __ Peter Gold KnowHow ProService ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Cross-ref formats
You can also make the punctuation and quotation marks a moot point by italicizing the book title, chapter title, heading, or other object, which would greatly reduce the number of cross-refs that you need. If it was me, I'd think about two templates with identically names cross-ref formats -- one with page numbers and one without, for print/PDF and online output. Then apply the appropriate format depending on the type of output. Art Art Campbell art.campb...@gmail.com ... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl. -- Richard Thompson No disclaimers apply. DoD 358 On Tue, Aug 4, 2009 at 2:55 PM, William Abernathywill...@inch.com wrote: First, figure out your standard cross-reference style. See Appendix D See Appendix D, Frying Pans and Toasters, See Appendix D, Frying Pans and Toasters, on p. 247 See Frying Pans and Toasters on p. 247 Whatever it's going to be, standardize as much as you can. Think about whether the style you select works with headed paragraphs as well as chapters/appendices. Do your paragraphs have heading numbers? Should these be included in the cross-reference definitions? Bust out your Chicago Manual and choose wisely, Luke. Concerning the punctuation inside the terminal quote, you can either pick a style that moots it (any of the above examples, except the second) or you add two styles, one for commas, another for periods. In a template I built, I called these xref tags +p and +c (for an added period or comma) styles, e.g. ChapterXref+p. In the second example above, you could dispense with the +c xref definition, because the title is an appositive and must be offset with commas, but you would still need a +p to bring it on home. --William Nancy Allison 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? ___ You are currently subscribed to Framers as will...@inch.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/william%40inch.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as art.campb...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Cross-ref formats
Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references in text are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be bound is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: See open italics Pots and Pans close italics on page 85, where Pots and Pans is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Cross-ref formats
The Microsoft Manual of Style has this as a couple of the ways to define cross-references: Correct see Formatting an Outline, p. 226. see Chapter 17, Outlining and Organizing a Document. For information about using the Outlining toolbar, see Starting an Outline, page 221. For information about using the Outlining toolbar, see Starting an Outline in Chapter 17, Outlining and Organizing a Document. For information about using the Outlining toolbar, see Starting an Outline earlier in this chapter. -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 2:52 PM To: framers@lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references in text are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be bound is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: See open italics Pots and Pans close italics on page 85, where Pots and Pans is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Cross-ref formats
Book titles are italicized, but chapter titles (and titles of book sections, figures, tables, etc.) are normally set in quotes. Italicizing these features is a bad hack, putting the needs of the writer ahead of those of the user. I'm curious: could your two-template approach be automatable using structure and some special DTD magic? --William Art Campbell wrote: You can also make the punctuation and quotation marks a moot point by italicizing the book title, chapter title, heading, or other object, which would greatly reduce the number of cross-refs that you need. If it was me, I'd think about two templates with identically names cross-ref formats -- one with page numbers and one without, for print/PDF and online output. Then apply the appropriate format depending on the type of output. Art Art Campbell ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Cross-ref formats
I use plain-text body font with cross-ref color (blue). There were so many legitimate cross-refs in a doc I inherited that the italics were incredibly distracting. I changed them all...regards, Kelly Stuck-in-the-mud McDaniel. -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 2:52 PM To: framers@lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references in text are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be bound is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: See open italics Pots and Pans close italics on page 85, where Pots and Pans is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as kmcdan...@pavtech.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/kmcdaniel%40pavtech. com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Cross-ref formats
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: XrefChapter\ $chapnum,Default ¶ Font \`$paratext,\' XrefChapter\ $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 Xrefpage\ $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 arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Cross-ref formats
Considering she's setting up a template for a print document, it makes sense to include the page numbers in the x-ref formats. If she's outputting to a different format, she can create a separate set of x-ref definitions in the tool she is using to create her other output. Mike -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Sharon Burton Sent: Tuesday, August 04, 2009 4:18 PM To: 'Nancy Allison'; framers@lists.frameusers.com Subject: RE: Cross-ref formats Given that more and more information is being repurposed, I've become against making things fit the old printed model. The xref formats you describe are from print. But I'm thinking more and more of formatting and content as separate. I would set the xrefs as simple as possible in Frame to handle other outputs. But that's just me. I'd rather not have writers trying to figure out what to use when and I'd really like to not have checking these formats in the preproduction list. sharon Sharon Burton IM: sharonvbur...@yahoo.com 951-369-8590 -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 12:52 PM To: framers@lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references in text are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be bound is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: See open italics Pots and Pans close italics on page 85, where Pots and Pans is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as mike.feims...@acstechnologies.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/mike.feimster%40acst echnologies.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Cross-ref formats
Right now she's doing print. But in 6 months? I like to build for this possibility. And I'm lazy and don't want to have to worry about what template is applied and checking the xref formats to make sure it's all as it should be and... I'm not saying Nancy is wrong, I'm just giving my philosophy on what I prefer to do. sharon Sharon Burton IM: sharonvbur...@yahoo.com 951-369-8590 -Original Message- From: Mike Feimster [mailto:mike.feims...@acstechnologies.com] Sent: Tuesday, August 04, 2009 1:33 PM To: sha...@anthrobytes.com; framers@lists.frameusers.com Subject: RE: Cross-ref formats Considering she's setting up a template for a print document, it makes sense to include the page numbers in the x-ref formats. If she's outputting to a different format, she can create a separate set of x-ref definitions in the tool she is using to create her other output. Mike -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Sharon Burton Sent: Tuesday, August 04, 2009 4:18 PM To: 'Nancy Allison'; framers@lists.frameusers.com Subject: RE: Cross-ref formats Given that more and more information is being repurposed, I've become against making things fit the old printed model. The xref formats you describe are from print. But I'm thinking more and more of formatting and content as separate. I would set the xrefs as simple as possible in Frame to handle other outputs. But that's just me. I'd rather not have writers trying to figure out what to use when and I'd really like to not have checking these formats in the preproduction list. sharon Sharon Burton IM: sharonvbur...@yahoo.com 951-369-8590 -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 12:52 PM To: framers@lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references in text are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be bound is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: See open italics Pots and Pans close italics on page 85, where Pots and Pans is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as mike.feims...@acstechnologies.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/mike.feimster%40acst echnologies.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to Framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Cross-ref formats
It sounds to me like we're all discussing the same philosophy: That things should be easy, controllable, and understandable. If a print paradigm is most comfortable, then create books with chapters the requisite # of headings. If topic-based authoring seems most straightforward, then go that route. AFIK, all the tools one might consider will give a nod to print (Word, PDF, and good ol' File Print), to Help output, and to structure via DITA or another model. I've always preached that the xrefs should be complete units where possible. This allows for consistency and accuracy in entering them, and for better understanding, albeit less variety, for the end user. Now that documentation=printed/PDF manuals=Help=training, the ability to manage xref formats from 1 template per output is (for me my clients)is non-negotiable. I choose to limit the choices in xref formats to the minimum, mapping to appropriate formats for various outputs (read as on import to RoboHelp) I limit my formatting to 95% of what I want to keep my doc's under control, rather than jumping thru the endless hoops needed to achieve 100% of what others perceive as perfect -Matt Matt Sullivan GRAFIX Training m...@grafixtraining.com www.grafixtraining.com office 714 960-6840 cell txt 714 585-2335 sms message skype: mattrsullivan twitter: mattrsullivan -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Sharon Burton Sent: Tuesday, August 04, 2009 1:48 PM To: 'Mike Feimster'; framers@lists.frameusers.com Subject: RE: Cross-ref formats Right now she's doing print. But in 6 months? I like to build for this possibility. And I'm lazy and don't want to have to worry about what template is applied and checking the xref formats to make sure it's all as it should be and... I'm not saying Nancy is wrong, I'm just giving my philosophy on what I prefer to do. sharon Sharon Burton IM: sharonvbur...@yahoo.com 951-369-8590 -Original Message- From: Mike Feimster [mailto:mike.feims...@acstechnologies.com] Sent: Tuesday, August 04, 2009 1:33 PM To: sha...@anthrobytes.com; framers@lists.frameusers.com Subject: RE: Cross-ref formats Considering she's setting up a template for a print document, it makes sense to include the page numbers in the x-ref formats. If she's outputting to a different format, she can create a separate set of x-ref definitions in the tool she is using to create her other output. Mike -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Sharon Burton Sent: Tuesday, August 04, 2009 4:18 PM To: 'Nancy Allison'; framers@lists.frameusers.com Subject: RE: Cross-ref formats Given that more and more information is being repurposed, I've become against making things fit the old printed model. The xref formats you describe are from print. But I'm thinking more and more of formatting and content as separate. I would set the xrefs as simple as possible in Frame to handle other outputs. But that's just me. I'd rather not have writers trying to figure out what to use when and I'd really like to not have checking these formats in the preproduction list. sharon Sharon Burton IM: sharonvbur...@yahoo.com 951-369-8590 -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 12:52 PM To: framers@lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references in text are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be bound is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: See open italics Pots and Pans close italics on page 85, where Pots and Pans is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as mike.feims...@acstechnologies.com
Cross-ref formats
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?
Cross-ref formats
First, figure out your standard cross-reference style. See Appendix D See Appendix D, "Frying Pans and Toasters," See Appendix D, "Frying Pans and Toasters," on p. 247 See "Frying Pans and Toasters" on p. 247 Whatever it's going to be, standardize as much as you can. Think about whether the style you select works with headed paragraphs as well as chapters/appendices. Do your paragraphs have heading numbers? Should these be included in the cross-reference definitions? Bust out your Chicago Manual and choose wisely, Luke. Concerning the punctuation inside the terminal quote, you can either pick a style that moots it (any of the above examples, except the second) or you add two styles, one for commas, another for periods. In a template I built, I called these xref tags +p and +c (for an added period or comma) styles, e.g. ChapterXref+p. In the second example above, you could dispense with the +c xref definition, because the title is an appositive and must be offset with commas, but you would still need a +p to bring it on home. --William Nancy Allison 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? > > ___ > > > You are currently subscribed to Framers as william at inch.com. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to framers-unsubscribe at > lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/william%40inch.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. > >
Cross-ref formats
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 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?
Cross-ref formats
On Tue, 04 Aug 2009 13:33:19 -0500 (CDT), 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. > . . . >What is your solution? Simple; I follow International English (UK) usage, and keep the punctuation *outside* the quotes: ---See Appendix D,?"Frying Pans and Toasters", for more information. ---For more information, see Appendix D,?"Frying Pans and Toasters". Most of the world, including those in the US, won't even notice. And it is more logical; the punctuation is *not*, after all, part of the quoted information. Consider: ---I don't know why she said "No!" ---I don't know why she said "No"! The meaning is different. In the first case, the speaker exclaimed. In the second, the narrator is exclaiming instead. Use the one that describes the situation more accurately. I'd even revise the first one so as to remove all doubt, as: ---I don't know why she said "No!". which makes it clear that the speaker, not the narrator, was doing the exclaiming. HTH! -- Jeremy H. Griffith, at Omni Systems Inc. http://www.omsys.com/
Cross-ref formats
On Tue, Aug 4, 2009 at 1:55 PM, Les Smalley wrote: > 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 As usual, Les has hit the nail! It's a good solution unless your style guide is iron-clad in its support of the common usage of enclosing quoted material in double quotes. Although these citations are quotes, they are also source names; it's common to use italics or other emphasis property to identify source names, such as these heading titles. I'd add the suggestion that you create a uniquely-named character format, for example, "head_cite," that applies only the unique text properties to the referenced material; this makes it easy to modify the appearance, if necessary, without affecting "Emphasis, bold" or other defined character formats. HTH Regards, Peter __ Peter Gold KnowHow ProService
Cross-ref formats
You can also make the punctuation and quotation marks a moot point by italicizing the book title, chapter title, heading, or other object, which would greatly reduce the number of cross-refs that you need. If it was me, I'd think about two templates with identically names cross-ref formats -- one with page numbers and one without, for print/PDF and online output. Then apply the appropriate format depending on the type of output. Art Art Campbell art.campbell at gmail.com "... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl." -- Richard Thompson No disclaimers apply. DoD 358 On Tue, Aug 4, 2009 at 2:55 PM, William Abernathy wrote: > First, figure out your standard cross-reference style. > > See Appendix D > See Appendix D, "Frying Pans and Toasters," > See Appendix D, "Frying Pans and Toasters," on p. 247 > See "Frying Pans and Toasters" on p. 247 > > Whatever it's going to be, standardize as much as you can. Think about whether > the style you select works with headed paragraphs as well as > chapters/appendices. Do your paragraphs have heading numbers? Should these be > included in the cross-reference definitions? Bust out your Chicago Manual and > choose wisely, Luke. > > Concerning the punctuation inside the terminal quote, you can either pick a > style that moots it (any of the above examples, except the second) or you add > two styles, one for commas, another for periods. In a template I built, I > called > these xref tags +p and +c (for an added period or comma) styles, e.g. > ChapterXref+p. > > In the second example above, you could dispense with the +c xref definition, > because the title is an appositive and must be offset with commas, but you > would > still need a +p to bring it on home. > > --William > > > Nancy Allison 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? >> >> ___ >> >> >> You are currently subscribed to Framers as william at inch.com. >> >> Send list messages to framers at lists.frameusers.com. >> >> To unsubscribe send a blank email to framers-unsubscribe at >> lists.frameusers.com >> ?or visit >> http://lists.frameusers.com/mailman/options/framers/william%40inch.com >> >> Send administrative questions to listadmin at frameusers.com. Visit >> http://www.frameusers.com/ for more resources and info. >> >> > > ___ > > > You are currently subscribed to Framers as art.campbell at gmail.com. > > Send list messages to framers at lists.frameusers.com. > > To unsubscribe send a blank email to > framers-unsubscribe at lists.frameusers.com > or visit > http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com > > Send administrative questions to listadmin at frameusers.com. Visit > http://www.frameusers.com/ for more resources and info. >
Cross-ref formats
The Microsoft Manual of Style has this as a couple of the ways to define cross-references: Correct see "Formatting an Outline," p. 226. see Chapter 17, "Outlining and Organizing a Document." For information about using the Outlining toolbar, see "Starting an Outline," page 221. For information about using the Outlining toolbar, see "Starting an Outline" in Chapter 17, "Outlining and Organizing a Document." For information about using the Outlining toolbar, see "Starting an Outline" earlier in this chapter. -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 2:52 PM To: framers at lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references "in text" are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be "bound" is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: "See Pots and Pans on page 85," where "Pots and Pans" is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy
Cross-ref formats
Book titles are italicized, but chapter titles (and titles of book sections, figures, tables, etc.) are normally set in quotes. Italicizing these features is a bad hack, putting the needs of the writer ahead of those of the user. I'm curious: could your two-template approach be automatable using structure and some special DTD magic? --William Art Campbell wrote: > You can also make the punctuation and quotation marks a moot point by > italicizing the book title, chapter title, heading, or other object, > which would greatly reduce the number of cross-refs that you need. > > If it was me, I'd think about two templates with identically names > cross-ref formats -- one with page numbers and one without, for > print/PDF and online output. Then apply the appropriate format > depending on the type of output. > > Art > > Art Campbell
Cross-ref formats
I use plain-text body font with cross-ref color (blue). There were so many legitimate cross-refs in a doc I inherited that the italics were incredibly distracting. I changed them all...regards, Kelly "Stuck-in-the-mud" McDaniel. -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 2:52 PM To: framers at lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references "in text" are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be "bound" is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: "See Pots and Pans on page 85," where "Pots and Pans" is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as kmcdaniel at pavtech.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/kmcdaniel%40pavtech. com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Cross-ref formats
Given that more and more information is being repurposed, I've become against making things fit the old printed model. The xref formats you describe are from print. But I'm thinking more and more of formatting and content as separate. I would set the xrefs as simple as possible in Frame to handle other outputs. But that's just me. I'd rather not have writers trying to figure out what to use when and I'd really like to not have checking these formats in the preproduction list. sharon Sharon Burton IM: sharonvburton at yahoo.com 951-369-8590 -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 12:52 PM To: framers at lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references "in text" are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be "bound" is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: "See Pots and Pans on page 85," where "Pots and Pans" is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy
Cross-ref formats
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: Chapter\ <$chapnum>, \`<$paratext>,\' Chapter\ <$chapnum>, \`<$paratext>.\' I wouldn't mind a bit getting rid of the first. > 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: \`<$paratext>\' 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: <$paranum> <$paranumonly> <$paratext> page\ <$pagenum> HTH! Richard Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-777-0436 --
Cross-ref formats
Considering she's setting up a template for a print document, it makes sense to include the page numbers in the x-ref formats. If she's outputting to a different format, she can create a separate set of x-ref definitions in the tool she is using to create her other output. Mike -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Sharon Burton Sent: Tuesday, August 04, 2009 4:18 PM To: 'Nancy Allison'; framers at lists.frameusers.com Subject: RE: Cross-ref formats Given that more and more information is being repurposed, I've become against making things fit the old printed model. The xref formats you describe are from print. But I'm thinking more and more of formatting and content as separate. I would set the xrefs as simple as possible in Frame to handle other outputs. But that's just me. I'd rather not have writers trying to figure out what to use when and I'd really like to not have checking these formats in the preproduction list. sharon Sharon Burton IM: sharonvburton at yahoo.com 951-369-8590 -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 12:52 PM To: framers at lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references "in text" are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be "bound" is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: "See Pots and Pans on page 85," where "Pots and Pans" is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as mike.feimster at acstechnologies.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/mike.feimster%40acst echnologies.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Cross-ref formats
Right now she's doing print. But in 6 months? I like to build for this possibility. And I'm lazy and don't want to have to worry about what template is applied and checking the xref formats to make sure it's all as it should be and... I'm not saying Nancy is wrong, I'm just giving my philosophy on what I prefer to do. sharon Sharon Burton IM: sharonvburton at yahoo.com 951-369-8590 -Original Message- From: Mike Feimster [mailto:mike.feims...@acstechnologies.com] Sent: Tuesday, August 04, 2009 1:33 PM To: sharon at anthrobytes.com; framers at lists.frameusers.com Subject: RE: Cross-ref formats Considering she's setting up a template for a print document, it makes sense to include the page numbers in the x-ref formats. If she's outputting to a different format, she can create a separate set of x-ref definitions in the tool she is using to create her other output. Mike -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Sharon Burton Sent: Tuesday, August 04, 2009 4:18 PM To: 'Nancy Allison'; framers at lists.frameusers.com Subject: RE: Cross-ref formats Given that more and more information is being repurposed, I've become against making things fit the old printed model. The xref formats you describe are from print. But I'm thinking more and more of formatting and content as separate. I would set the xrefs as simple as possible in Frame to handle other outputs. But that's just me. I'd rather not have writers trying to figure out what to use when and I'd really like to not have checking these formats in the preproduction list. sharon Sharon Burton IM: sharonvburton at yahoo.com 951-369-8590 -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 12:52 PM To: framers at lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references "in text" are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be "bound" is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: "See Pots and Pans on page 85," where "Pots and Pans" is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___ You are currently subscribed to Framers as mike.feimster at acstechnologies.com. Send list messages to framers at lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscribe at lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/mike.feimster%40acst echnologies.com Send administrative questions to listadmin at frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Cross-ref formats
It sounds to me like we're all discussing the same philosophy: That things should be easy, controllable, and understandable. If a print paradigm is most comfortable, then create books with chapters & the requisite # of headings. If topic-based authoring seems most straightforward, then go that route. AFIK, all the tools one might consider will give a nod to print (Word, PDF, and good ol' File > Print), to Help output, and to structure via DITA or another model. I've always preached that the xrefs should be complete units where possible. This allows for consistency and accuracy in entering them, and for better understanding, albeit less variety, for the end user. Now that documentation=printed/PDF manuals=Help=training, the ability to manage xref formats from 1 template per output is (for me & my clients)is non-negotiable. I choose to limit the choices in xref formats to the minimum, mapping to appropriate formats for various outputs (read as "on import to RoboHelp") I limit my formatting to 95% of what I want to keep my doc's under control, rather than jumping thru the endless hoops needed to achieve 100% of what others perceive as "perfect" -Matt Matt Sullivan GRAFIX Training matt at grafixtraining.com www.grafixtraining.com office 714 960-6840 cell & txt 714 585-2335 sms message skype: mattrsullivan twitter: mattrsullivan -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Sharon Burton Sent: Tuesday, August 04, 2009 1:48 PM To: 'Mike Feimster'; framers at lists.frameusers.com Subject: RE: Cross-ref formats Right now she's doing print. But in 6 months? I like to build for this possibility. And I'm lazy and don't want to have to worry about what template is applied and checking the xref formats to make sure it's all as it should be and... I'm not saying Nancy is wrong, I'm just giving my philosophy on what I prefer to do. sharon Sharon Burton IM: sharonvburton at yahoo.com 951-369-8590 -Original Message- From: Mike Feimster [mailto:mike.feims...@acstechnologies.com] Sent: Tuesday, August 04, 2009 1:33 PM To: sharon at anthrobytes.com; framers at lists.frameusers.com Subject: RE: Cross-ref formats Considering she's setting up a template for a print document, it makes sense to include the page numbers in the x-ref formats. If she's outputting to a different format, she can create a separate set of x-ref definitions in the tool she is using to create her other output. Mike -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Sharon Burton Sent: Tuesday, August 04, 2009 4:18 PM To: 'Nancy Allison'; framers at lists.frameusers.com Subject: RE: Cross-ref formats Given that more and more information is being repurposed, I've become against making things fit the old printed model. The xref formats you describe are from print. But I'm thinking more and more of formatting and content as separate. I would set the xrefs as simple as possible in Frame to handle other outputs. But that's just me. I'd rather not have writers trying to figure out what to use when and I'd really like to not have checking these formats in the preproduction list. sharon Sharon Burton IM: sharonvburton at yahoo.com 951-369-8590 -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of Nancy Allison Sent: Tuesday, August 04, 2009 12:52 PM To: framers at lists.frameusers.com Subject: Re: Cross-ref formats Some follow-up questions: 1. I've been looking at the Chicago Manual, 15th edition. I'd expect a great honking treatment of this subject, but I'm not seeing it. All the cross-reference i9nformation is presented with reference to indexes and bibliographies. The sections referring to cross-references "in text" are discussions of the editor's obligation to check cross-references! Is there an exhaustive section on x-ref format, in text, that I'm missing? 2. I'm shocked, shocked, I tell you , to discover just what a stick-in-the-mud I really am. I thought italics were sacrosanct for referring to the titles of separately bound publications. (Although how purely electronic publications can be "bound" is a topic for another day.) But .. . you've all gotten over this hurdle and use italics to identify cross-references? Like: "See Pots and Pans on page 85," where "Pots and Pans" is a couple of paragraphs with header in a much longer chapter of a much larger *separately bound* publication, whether physical or digital? Really? I must sit down. In that case, do you also put your italicized x-refs in a different color, so as to distinguish them from the titles of separately bound publications, which you might also mention in your text? Thanks! --Nancy ___
