Cross-references won't update

[rlauriston]

Flare 6.1. I changed my cross-reference formats weeks ago. They're coming out right in both WebHelp and PDF output, but in the XML editor they're out of date. This is confusing and a waste of time as I keep thinking I've found nonexistent errors.

I know I can do Tools > Update Cross-References manually for each file. Is there no way to update globally? Maybe in Flare 7?

To me, this is a bug. I'd rather see tags than an out-of-date preview.

[LTinker68]

No, there's not a way to do it globally.

I'd also argue against classifying it as a bug. Don't forget that you can single-source the content. So say you have two different outputs, one for end users and one for admin users. The end users output might have 10 fewer topics, for instance. The admin users output might have those 10 topics, but interspersed among the rest of the topics. If you look in a topic that's in both outputs and have a xref to the last topic in the outputs, for example, then the page number in the xref will be different because one output has more pages than the other.

[rlauriston]

No, there's not a way to do it globally.

I'd also argue against classifying it as a bug. Don't forget that you can single-source the content. So say you have two different outputs, one for end users and one for admin users. The end users output might have 10 fewer topics, for instance. The admin users output might have those 10 topics, but interspersed among the rest of the topics. If you look in a topic that's in both outputs and have a xref to the last topic in the outputs, for example, then the page number in the xref will be different because one output has more pages than the other.

I think it's a bug for the XML editor to display a cross-reference using a format that no longer exists anywhere in the project.

[LTinker68]

Oh, sorry, I missed the word "formats" in your original post -- I thought you were talking about the value displayed for the xref.

Have you opened the stylesheet file in the Internal Text Editor and verified that you've completely changed that format? And you've double-checked it in both the default and print mediums and any others you might use? And if you have more than one stylesheet, you've either checked them all, or you've verified that your default target is pointing to the stylesheet where you made the changes (the XML Editor displays the content using the styles in the stylesheet associated with your default target).

[rlauriston]

Oh, sorry, I missed the word "formats" in your original post -- I thought you were talking about the value displayed for the xref.

Have you opened the stylesheet file in the Internal Text Editor and verified that you've completely changed that format? And you've double-checked it in both the default and print mediums and any others you might use? And if you have more than one stylesheet, you've either checked them all, or you've verified that your default target is pointing to the stylesheet where you made the changes (the XML Editor displays the content using the styles in the stylesheet associated with your default target).

Yes, quite sure. If I manually update for the current file everything is correct.

The values aren't updating either.

I don't get the argument that this is not a bug. The style does not exist, the x-ref'd headings no longer read as displayed. What's the use case for previewing out-of-date information?

[LTinker68]

In this case, yes, it does seem to be a bug. When I said before it wasn't a bug, I was referring to the contents of the xref not updating, not the format of the xref not updating. The contents will be a placeholder for some items and is resolved to the actual contents at build time.

If the format of the xref itself doesn't seem to be displaying in the XML Editor (e.g., it should be paranum but it's showing paranumonly), then I guess I'd open the topic in the Internal Text Editor and make sure it's pointing to the correct class of the xref tag and that there aren't any inline styles in the tag that could be overriding the stylesheet definition. I'd also open the stylesheet file in the Internal Text Editor and make sure I don't have two different sets of definitions for the same xref tag. And if you use complex selectors, make sure you're not in a situation where a definition for the complex selector would be called; if it is, make sure its definition is correct in the stylesheet.

Beyond that, I'd contact support to see if they could look at the project to see what the problem is.

[rlauriston]

If the format of the xref itself doesn't seem to be displaying in the XML Editor (e.g., it should be paranum but it's showing paranumonly), then I guess I'd open the topic in the Internal Text Editor and make sure it's pointing to the correct class of the xref tag ...

There's no mistake in my code. Like I said, if use Tools > Update Cross-References, the display is correct. If I don't, both values and formats are whatever they were when I inserted the x-ref.

When I said before it wasn't a bug, I was referring to the contents of the xref not updating, not the format of the xref not updating. The contents will be a placeholder for some items and is resolved to the actual contents at build time.

My cross-references are all to headings in the project. I changed almost every heading in the project a few weeks ago when I realized that I hadn't been following the style manual. So I keep seeing uncorrected headings and thinking I missed them.

I see no use case for Flare previewing uncorrected headings from weeks ago showing up in every topic. If Flare's not going to update such links, it should show abstract placeholders, not out-of-date values.

[LTinker68]

If Flare's not going to update such links, it should show abstract placeholders, not out-of-date values.

Yes, I agree. And I thought it did correct them when you do a build, but maybe not. Most of my xrefs are things like "see Figure 3 on page 4" which in the XML Editor appear as "see Figure 1 on page 1". That I've gotten used to and it makes sense to be a placeholder. I guess the times where I have done things like "see 'Forms' on page 8", I haven't noticed that the xref didn't change when I changed the heading in the referenced topic.

So, yes, I agree that Flare should either update xrefs in a topic when you open the topic, or it should update all topics at build time.

[NorthEast]

I think any option to update the placeholder text project-wide would only work if it was a manual option. You wouldn't want to do it automatically, as it'd potentially need to modify every single topic in the project; and you don't want to be doing that if you have multiple users and/or use source control.

Rather than use placeholder text, it would be good to have an option to display the current xref text (for the selected medium) when you open a topic; at least for para/heading text, rather than numbers. You'd probably have a slight delay when you open the topic though.

[Penthesilea]

I am in ver 8.1 and just stumbled across this undocumented feature. I will report it as a bug.

If we right-click the link, select Edit, and then just click OK, the link updates within the topic. Still, I would expect this to correct itself in the xml editor since the output is updated.

[Penthesilea]

From MadCap tech support:

Yes, as you have noted, if you make a change in the cross-reference format in the stylesheet, it does not automatically update it on the topic in the XML Editor. If Flare were to do this, it would need to write the changes to every topic that is using the cross-reference format. However, the changes do apply when you do a build of the project.

If you would like to see the changes updated in the XML Editor, you can do this by going to Tools > Update Cross-references. This will update it for the topic that you have open in the XML Editor.

[Msquared]

If you look in the XML that Flare generates for the topic, it actually hard-codes the text of the xref in the .htm file, as it would appear in your primary target. So, for example, in my primary target, xrefs are

See section 1.1.1 "Section Name"

and that actually appears in the .htm file. Therefore Tools > Update Xrefs does actually have to update the xrefs stored in the file. It doesn't just update a style tag and leave it to the XML editor to render it correctly on display. Goodness knows why they are hard-coded (numbered lists are done this way too) rather than just tagged ad resolved when the topic is built, but they are. I expect there is some reason for it that I don't appreciate (perhaps to make life easier for display by the XML Editor?).

However, this does mean that if you were to globally update all the xrefs in all the topics, the content of the topic has to be updated, so it will appear as a change to the topic. So it will be flagged as a changed topic that needs translation, although nothing has changed that needs to be translated, but the translators won't realise this until they get the topic, by which time they have probably included that in the count of changes topics that they have quoted you for . . .

This hard-coding of xref layouts can cause spectacularly wrong xrefs if the xref-ed topic is conditionally excluded in something that isn't your primary target. Flare doesn't spot that the xrefed topic is missing (bug, although some say this is a "feature"), and leaves something based on the old hard-coded xref text in your output.