Print vs. Online Xref formats: What's the trick?

[Phlawm53]

For Flare 6/7.

I've been using Flare for a bit more than year to generate mostly PDF outputs. Everything's been great.

But now I need to generate the content as a WebHelp system. And I'm having trouble formatting x-refs for online output.

• In print, I have a cross-reference of the form {i}{paratext}{/i}, on page {page}. It works great in PDFs.
• But I'm trying — and failing — to configure the non-print CSS to present the WebHelp system's xrefs as {i}{paratext}{/i}

Here's how I've been trying to get this to work:

1. In Flare 7 Stylesheet Editor, select Medium: Non-print, then in Madcap | xref locate the xref.

2. In the xref, "prune" the page number information so that {i}{paratext}{/i}, on page {page} becomes {i}{paratext}{/i}

3. Save the edited CSS file and regen the WebHelp target.

After performing the above steps, and a few variations thereof, the WebHelp system still includes the page number as part of the "edited" xref.

I've looked for other settings but so far haven't been successful. I suspect I'm overlooking something relatively obvious, but after about two days of trying to sort this out, I'm at wits end.

So can some please advise what I'm doing wrong?

Cheers & thanks,
Riley
SFO

[whunter]

Did you set the Web Help target to use the non-print stylesheet medium? I think it uses "default" by default, you need to manually change it to "non-print" if that's where you made the changes.

This is set on the Advanced tab of the target.

[Phlawm53]

W:

Doh! That's the control I've been trying to find for the past two days…

I'm not normally this clumsy with tools, but…well, there you have it…

Cheers & thanks much,
Riley
SFO

[LTinker68]

I don't recommend using the non-print medium. Use default for your online output and change only those tags and attributes that need to be changed for print outputs in the print medium. The print medium inherits from the non-medium (aka, the "default" medium), and the non-print medium inherits from the default medium, but the print medium doesn't inherit from the non-print medium or vice versa. So you're in effect making more work for yourself because you're having to input styles twice instead of once, with the occasional second time, as necessary, for print output.

[whunter]

You might also prefer to use different stylesheets for print and online. I find it easier that way, rather than messing around with the mediums.

Also, I swear I discovered that when you print from online help, it uses the settings defined in the print medium (which totally did not work out for me). Although that sounds odd now that I say it out loud.

[LTinker68]

Also, I swear I discovered that when you print from online help, it uses the settings defined in the print medium (which totally did not work out for me). Although that sounds odd now that I say it out loud.

Uh, that's by design. CSS and browser design, not Flare design. The print medium was originally created, so to speak, to handle the appearance of web pages when printed. Flare just happens to use it for controlling styles in print outputs, as well. In your case with two stylesheets, if you want your online output to change the appearance of web pages when printing, you should still use the print medium, but use the print medium in the same stylesheet you use for your online output. For example, say you have a rainbow-colored graphic to simulate a colorful border under your headings. While this might be fine for online outputs, you wouldn't necessarily want it to appear when the user printed that web page because that's just a waste of their color ink -- better to replace it with a black-and-white gradient graphic. Likewise, the various colors you use for your fonts, hyperlinks, etc., might appear ok on a monitor, but be too faint or hard-to-read on a printed color page, so better to set most text to be black in the output, except perhaps things you want to emphasize.

The print medium in a single stylesheet gets a bit tricky if your print output isn't for a standard-sized page. For example, if your print output is a 5 x 8 booklet, you might need to force page breaks in the output that you wouldn't want to happen when the user printed from the web page. So if your print output is a non-standard-sized page, then you either need to use two stylesheets as whunter does, or create a new medium for the 5x8 booklet so you can control its styles differently from the print medium used by the online output.

[Phlawm53]

Well, if mistakes and stumbles are how one learns, then stumbling over the formatting of xrefs in online help has enabled me (and I suspect others) to have learned quite a bit about CSS configuration for print and non-print mediums…

Thanks to all who have contributed with answers and information!

[tamsinjoy]

I am having trouble with PDF cross-references when I am reusing a topic in a project. The xref appears correct in PDF -- got the page number and link works, but it is referring to the 2nd use of the topic.

Let's say Topic A appears on page 3 and 50 in my PDF. On page 1, I have an xref to Topic A, but the PDF output refers to Topic A on page 50, when I really want it to point to the first instance of Topic A on page 3.

What gives? :s

[whunter]

If you've got the same topic in two locations, I don't think there's any way to tell it which one to point to. As a work around, you can put the body text of the topic in a snippet, then create two different topics that contain the snippet text. Then you can point the x-ref to the specific topic you want to use.

[tamsinjoy]

Thanks, whunter!

Isn't this defeating single sourcing though? I was looking at the TOC for my PDF target -- if I could link to the first instance of the topic in that, then it'd work. Is this possible?

[Phlawm53]

Regarding the comment by "tamisjoy":

The xref appears correct in PDF -- got the page number and link works, but it is referring to the 2nd use of the topic.

Completely off the top of my head, but have you tried using the h1 through h6 cross-reference building blocks?

In the New Cross-Reference Style Class dialog box (used to create or edit x-refs), the explanatory text for h1 states "Text of first heading 1 paragraph". Moreover, when I first started using Flare 6, part of my learning was that use of the h1 building block caused instances of that type of x-ref to always point to the first h1 instance; I had to quit using the h1 building block because of that behavior…

My apologies if this isn't actually the answer to your problem (I'm hurrying a bit today), but thought you might take a look at it if you hadn't already…

Cheers,
Riley

[LTinker68]

Isn't this defeating single sourcing though? I was looking at the TOC for my PDF target -- if I could link to the first instance of the topic in that, then it'd work. Is this possible?

whunter's suggestion is more useful in online outputs because 1) it works better with syncing the TOC (the TOC doesn't jump to an entirely different book, for example), and 2) it keeps the breadcrumbs in sync with where you are, if you're using breadcrumbs.

Generally you wouldn't want to repeat a topic in a print output. Why would you -- you'd just use cross-references. So in this situation, I'd follow whunter's suggestion for online output, then I'd condition out one of the topics from print output and I'd point all my xrefs to the topic that wasn't conditioned out. So the project is still single sourced because your topic content can be changed in one location (the snippet file).

BTW, I'd also set one of those topics to not be searchable -- that way the end user won't pull up two identical topics in search results.

[tamsinjoy]

Awesome, Lisa. Thanks this is clear to me!! I will try that. And on we both learn, Phlawm53!