XREF shows classes for all media types

This forum is for all Flare issues related to styles, stylesheets and XML.
Post Reply
oremphelyn
Jr. Propeller Head
Posts: 8
Joined: Tue Nov 06, 2018 4:44 pm

XREF shows classes for all media types

Post by oremphelyn »

When creating a cross reference, Flare displays all XREF classes for all media types. This is inconsistent with how it displays in all other parts of the document only CSS classes for the active media type.

Background

I created a single CSS document for all of our various document types: datasheets, manuals, field wiring diagrams, etc. Each document type is a separate media type. Each media type contains, for example, a specific CSS definition for body, p, H1, etc. Each also defines a XREF style specific to the document type.

For example, one media type defines XREF with three styles:

Media type A:
XREF mc-format: 'See {quote}{paratext}{quote} on page {page}';
XREF.FigureNrOnly mc-format: '{paranumonly}';
XREF.NoSee mc-format: '{quote}{paratext}{quote} on page {page}';

Other media types define XREF differently:

Media type B:
XREF mc-format: '{paratext}';

Media type C:
XREF mc-format: '{paratext} {pageref}';

Issues

However, when I create a XREF, the Insert Cross Reference dialog box displays all XREF classes for all media types. This creates several potential problems.

A) The XREF definitions for the active media type are not shown in order. The two Media Type A styles "XREF.FigureNrOnly" and "XREF.NoSee" lead the list and are displayed using a blue color. (I assume the blue color indicates that the XREF definition is part of the active media type.) However, Media Type A XREF is displayed in blue at the bottom of a list of all styles from all media types. If the user knows that blue indicates the active media type, they may assume that the first items displayed in blue represent ALL of the XREF styles available for that media type, and may not know that they must scroll to the bottom of the list to see another choice.

B) The ability to pick a CSS style from another media type is inconsistent with all other uses of CSS styles in Flare. The conflicting definitions of XREF made in Media Type B and C are not displayed. Displaying all media types creates a problem when two CSS styles from different media types use the same name.

C) A user may unwittingly choose a XREF Class from another media type and edit it to their liking, and create subsequent problems for other documents based on that media type.

Flare should be internally consistent and not display XREF classes from a different media type.

Has anyone else seen this issue?

Thanks for your input.
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: XREF shows classes for all media types

Post by ChoccieMuffin »

I think I understand what you're getting at, and it is, I think, working as designed. When you insert a cross-reference, the default is to insert the basic one (MadCap:XRef). You only need to select something from the list if you want to add a class to the x-ref.

What is shown in your XML editor depends what medium is set for the Primary target. What appears in your outputs depends on what medium is set for each target, not what you see in the XML editor, because Flare generates the x-ref again when generating the final output. (I find this very irritating when I'm working using my PDF medium and layout, because it shows "xxx on page 1" in the XML Editor when I just want it to show "xxx" formatted in blue, which is what my online medium uses.) Also, if you apply a class that doesn't exist in the medium used for the target you're producing, the output just contains the item styled as the parent class (in this case XREF).

So if Target A (the output that uses Media type A) is set as Primary (you do this in the Project Organizer, right-click the target and select Make Primary) then that is how an ordinary xref is inserted. So any time you insert an XREF (without an extra class) then your XML Editor will display "xxx" on page 1, because that's how you've defined it for that medium. If you instead insert XREF.NoSee your XML editor displays "xxx" on page 1. If you then generate Target B, the output will contain just "xxx" whether you've got ".NoSee" set or not, because that is how you have defined the basic XREF.

A problem might indeed arise if your colleagues are able to edit the stylesheets and then go messing around with the XREF attibutes in the wrong medium, but that should be a matter of education (in other words, tell 'em not to! :-D ). To resolve the issue, they should think about how the topic would need to be displayed in outputs using Media type A and apply the appropriate style. I am guessing that your default even for Target A is the most commonly used one, so it shouldn't be a problem if they just insert XREF - they would only need to select a different class of cross-reference if they specifically want the x-ref in the output to be different.

If you find it annoying to have your cross-refs displaying with "on page 1" when you're editing a topic, you can change how things are displayed in the XML Editor. First change the Layout and Medium in the local toolbar of the XML Editor to the thing you want to use, then on the Tools tab click Update Cross-References.

Incidentally, in your Media type A you could replace "on page {page}" with "{pageref}" because it's the same thing.

I hope I haven't told you stuff you already know, and that this post is helpful in some way.

For anyone looking at x-refs, here's the landing page for it in the 2018 help: http://help.madcapsoftware.com/flare201 ... references
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
Post Reply