Links vs Cross-Ref

[cayennep]

The jumpstart course advised to use cross-refs instead of links. Can't remember all the reasons but it sounded good, everything updates better, etc.

However, I'm used to being able to link a topic to some text and have the text just show as a hyperlink in the tool (Flare). Then I set the link type to put 'topic name + page #' in print output, but just display a hyperlink in html.

Can anyone talk me through how to do this in Flare? Using a cross-ref, it displays "see topic blah" which of course I don't want and don't see how to easily change the text. Looks like it involves creating a style, a new xref that uses that style? Then how do I make it different for print vs online?

Basic steps would be great, still trying to wrap my head around this tool.

thx kindly!

[LTinker68]

In the Insert Cross-Reference screen, there is a button for creating a new cross-reference format. Click that and set the format for the xref as you want it to appear for online output. Save the new xref format and close the screen.

Open the stylesheet in the Stylesheet Editor and set it to the default medium. Scroll down to MadCap|xref, expand the group if in Advanced view, then click on the new one you just created to select it. Look for the attribute mc-format. It should display the text you specified when you created the xref. Now switch the Stylesheet Editor to the print medium. The mc-format attribute for the print medium will have a default format for print (specified in the language skin if one was selected, otherwise using the built-in default). If the Stylesheet Editor is in Simplified view, you can click on the value of the mc-format field to bring up the Properties screen, then click the Edit button to get to the Cross-Reference screen so you can format the xref. (If you're in Advanced view in the Stylesheet Editor, double-clicking the attribute takes you directly to the Cross-Reference screen.) Set the format you want for the xref in print output then save the changes. If you switch between default medium and print medium then you'll see the different values specified for that xref format.

[ChoccieMuffin]

Cayenne, I sympathise.

You can format cross-refs any way you like, so for printed output it says "see Title on page 23", with or without quote marks, with or without formatting etc etc etc, and with the same cross reference (so you don't have to make any changes to your source file) you can make the cross reference just say Title, underlined in blue etc etc.

When you insert the cross-ref, the cross-ref properties in the bottom of the dialog show how things are set up for the current style and medium that you are using, so for example if you are using Print as your medium, Madcap:xref displays as See "Title" on page 1. Whichever cross-ref class you choose to use, that's the one you now need to edit in the style sheet. You can click Edit from that dialog box, and that gives you the chance to remove the "see" or the quote marks, or format it as you see fit.

If you're using different mediums, you need to edit that x-ref class in the other medium. If you decide to duplicate your stylesheet for other outputs (e.g. one stylesheet for printed docs, another for webhelp) then you edit that style in your other stylesheet.

Hope that helps. And if it's any encouragement, if I can do it, anyone can, so I have every confidence in you. I share the pain of being a newbie to Flare, but these forums are being very helpful.

[cayennep]

Thanks so much, folks!
This is fantastic help, clear and in the right order and all the details are there. Or so it seems, we'll see when I try and do it

I've used Author-it extensively and there are not nearly so many steps required. Course Flare has its definite advantages too, cost and customer service/responsiveness not the least, but still in the learning curve for sure. In ait, you have a jump object and go to the object properties to tell it how to behave in the various outputs. Much simpler, but again wrapping my head around a different way to do things takes time.

What I would find really helpful is discussion around the relationships between all these different things, cos there are a LOT!! Style, medium, target, conditions - and the hierarchy, etc.

while you're here, on conditions - you make a condition then set it in the target to be on or off? or in the medium, then target uses a medium? this seems like a task you have to do a lot... will make a separate post when I get there, but off to try this stuff now.

Thanks again!

[cayennep]

Also, what are the advantages of using xref instead of just a link? Linking to a topic is MUCH easier, so now I'd like justification for doing this (tho like many things Flare, once it's done it's done. I think.)

thanks again

[ChoccieMuffin]

I think (but I could be wrong) that it's to do with the flexibility of a cross-ref. You can make it look like a simple link if you like, but if someone comes along 6 months from now and tells you they want you to do a printed manual from your help stuff, you would be stuffed if you've only got links. Also not sure how the links actually work, there may be some problem with moving the target of links and then the links breaking, but I'm predominantly doing PDFs as output and not helps so I could be wrong.

[LTinker68]

Another advantage is if you use a xref and it's set to show text, say the title of a topic, and you change the title, the xref will automatically update to reflect the change when you build the output. Hrefs, on the other hand, are hard-coded as to what the text of the link says, so you'd have to find all the links with the old text and change them.

Plus, you can't do medium-specific text changes on hrefs, like you can with xref (e.g., "see Configuring the Software" for online and "see Chapter 9" for print).

[cayennep]

Thankyouthankyouthankyou!!

that makes it all worthwhile, I do remember it was really useful and this was why, even if initially not quick to set up.

v. helpful, thx again

[John Owens]

Plus, you can't do medium-specific text changes on hrefs, like you can with xref (e.g., "see Configuring the Software" for online and "see Chapter 9" for print).

One thing to look out for is that Flare will not update your cross-reference automatically depending on which Medium is specified for the target, if the xref is pointing to a topic outide of the current TOC during generation. For example when you have two TOC and one only contains a subset of the topics, such as for a specific print target, and the other TOC includes all topics, such as for online output. It all depends on whether or not your Flare XML Editor was in the Medium Print mode when you created the Xref or updated the Xref. If it was not, then no matter which Medium you select for the Target it will use the default one instead.

[LTinker68]

One thing to look out for is that Flare will not update your cross-reference automatically... If it was not, then no matter which Medium you select for the Target it will use the default one instead.

It'll be updated at build-time, it's just in the authoring mode it won't be updated. You can update it manually. I don't have Flare open at the moment, but I think under Tools or Project there is an option to update cross-references, although it'll only update them in the current topic. The page number reference, however, will almost always show page 1, unless you're pointing to another spot in the same topic. The reason it's always page 1 is because it's not until the output is built that it can calculate what the actual page number will be, so the page 1 in this case is a placeholder.

[Andrew]

One thing to look out for is that Flare will not update your cross-reference automatically... If it was not, then no matter which Medium you select for the Target it will use the default one instead.

It'll be updated at build-time, it's just in the authoring mode it won't be updated. You can update it manually. I don't have Flare open at the moment, but I think under Tools or Project there is an option to update cross-references, although it'll only update them in the current topic. The page number reference, however, will almost always show page 1, unless you're pointing to another spot in the same topic. The reason it's always page 1 is because it's not until the output is built that it can calculate what the actual page number will be, so the page 1 in this case is a placeholder.

I think John Owens is pointing out that, if your xref target is not included in your output, Flare does not update the xref text, but rather, it uses whatever text Flare inserted into the XML Editor when you created the xref (which will be something like "see blahblah on page 1" for print, or just blahblahblah for default / non-print). Normally, that text is replaced when you build a target, but if the xref target topic is not in the output (such as print docu when the topic is not in the TOC), Flare does not replace that text, because the reference doesn't exist in the target.

It's an interesting issue...generally, I would condition such an xref so it did not appear in that target's output, but that's rather manual and annoying. But I'm not sure what the best behavior would be for Flare to handle it automatically.

[cayennep]

I have to say, Andrew, I have no idea what you're saying here.

xref target? you mean the topic the xref points to? it is included, so if that's what you mean it's not the problem.

However, I changed the xref for print output so that it adds on page {#} and it is NOT updating!! Have I managed to break something again, or is this single-source tool really, well, not?

thx

[lacastle]

However, I changed the xref for print output so that it adds on page {#} and it is NOT updating!!

Where is it not updating? In the generated PDF, or the generated webHelp, or the topic editor?

Also remember that when you make changes to a style, you have to click out of that line item for the change to take effect, and then save the stylesheet. I've made changes in the past and thought i saved them, but actually they never were applied.

[Andrew]

I have to say, Andrew, I have no idea what you're saying here.

xref target? you mean the topic the xref points to? it is included, so if that's what you mean it's not the problem.

However, I changed the xref for print output so that it adds on page {#} and it is NOT updating!! Have I managed to break something again, or is this single-source tool really, well, not?

thx

Ah, my apologies, I thought your question had been answered, and I was responding more to Lisa (who I hope can follow my spaghetti thoughts).

Yes, the "xref target" is the topic to which the xref points.

Where is the xref not updating? It won't update, typically, in Flare (unless you open the topic and select Tools > Update Cross-References). Also, you must have the medium set to Medium (print) in the XML Editor (the XML Editor is Flare's normal authoring word processor). You can see the medium in the editor's toolbar: it's a drop-down right next to the layout drop-down, directly above the topic's content. It typically defaults to the primary target's output medium.

[LTinker68]

I guess I'm having trouble trying to figure out why you're cross-referencing to something in a different document. There would be so many problems or issues related to that. For example...

• You'd have to build the other output first so that its internal xrefs were updated so that you're getting the latest xref info in this document.
• In addition, since you can have multiple outputs in a project, how does a xref know which output to use when it builds the xref? Should it assume you want the print page number? And what if you have multiple print outputs? How does it know which one to use?
• You would have to keep both documents in sync, not only internally but in what your end users have, because otherwise you could be using a xref for a version of the other document that they don't have, so the xref wouldn't match their document anyway. Which would lead to confusion, calls to tech support, and general user dissatisfaction.

Why not do a generic textual reference, like "see the Installation Guide for more information".

[Andrew]

I think I might be able to provide an example of why you'd xref something in a different document. Frequently, you'll have two separate print documents that come from one project (User Guide and Admin Guide, for example). You may *also* have a WebHelp or HTML Help output that includes ALL that information. In the WebHelp, you want to be able to link to the relevant admin topics from the user topics. However, those same links make no sense in the print versions.

That's why I said I'd condition those links -- they really shouldn't exist in the print output. It would be nice if Flare was "smarter" about how it handled xrefs outside the current project; it might be cool to be able to select a build target and xref between manuals, for example, but as you already pointed out, there are a lot of caveats and problems.

[John Owens]

Here is the issue...hopefully explained a little clearer.
This is an email I recently sent to MadCap concerning a bug in which Flare does NOT update Xrefs at build time, in some conditions.

Main Issue: XRefs do not automatically update depending on which medium (default, Online, Print...) is assigned to the target.

Flare documentation says that it does but it doesn't. See the excerpt below:

Updating cross-references is not a mandatory step. When you generate output for a target, all of your cross-references will be updated automatically. However, you can use this feature to manually update cross-references in a single topic. This is a way of performing a "spot check" ahead of time, verifying that cross-references will be updated accurately before you generate the output.

Output all depends on which mode the Flare XML Editor is in when creating or updating an XRef. If the Flare XML Editor was in Print medium mode, then the Print Medium version of the XRef will be saved in the topic’s xml code, so it will work. However, if I create or update the XRef with the Flare XML Editor in default or Online medium mode, then the Online/Default version of the XRef will be added to the topic’s xml code. Then when I use a Print target which is assigned the Print medium, because the link is external, it does not update as it should. Instead it uses the Default or Online medium’s XRef.

Example:
Default Medium in CSS

Code: Select all

MadCap|xref.OtherDocSameProject
{
      mc-format: 'Refer to {i}{paratext}{/i}.';
}

Print Medium in CSS

Code: Select all

MadCap|xref.OtherDocSameProject
{
      mc-format: 'Refer to our XYZ document.';
}

Topic with Xref created in Flare Default Medium mode:

Code: Select all

        <p><MadCap:xref href="../Parental/PC_Comm.htm" target="" title="" alt="" class="OtherDocSameProject">Refer to <i>Parental Control Commands</i>.</MadCap:xref></p>

Topic with Xref created in Flare Print Medium mode:

Code: Select all

        <p><MadCap:xref href="../Parental/PC_Comm.htm" target="" title="" alt="" class="OtherDocSameProject">Refer to our XYZ document.</MadCap:xref></p>

Flare documentation states that the actual text placed in the XRef does not matter, as it will be updated depending on which target is used. This is Not true.

Since the second example was created and saved while in Flare XML Editor Print mode, then the topic will display correctly in all target mediums. However, if I create and save the topic as in the first example, in Flare XML Editor Default mode, then the topic will only generate correctly for targets assigned the Default medium. When I generate a target using the Print medium, the topic does not update and it displays the Default XRef instead.

So, it seems that the bug is that Flare does not update the XRefs before generating the targets, If the XRef is external.

If we always remember to create and save topics with Flare XML editor in Print medium mode then all will be fine. However this is too much to expect, surely someone will forget somewhere along the way.

End of email:
So, we are back to adding conditions to Xrefs. If this issue was fixed then we could only use one custom Xref and forget about the conditions.