How can I customize an <xref> output?

This forum is for all Flare issues related to styles, stylesheets and XML.
Post Reply
luvthepug
Propeller Head
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

How can I customize an <xref> output?

Post by luvthepug »

I want to know if there is a way to modify the text of a cross-reference. I am using Flare 2019 and my output is WebHelp and HTML/chm.

BTW, I know I can use an <href> to achieve what I want, but I want the updating features that <xref>s offer and <href>s don't.

Here is my scenario:

I have a top-level book in my TOC called Performance Tests. Each topic under that book is a different test each with its own title. For example, one of the topics has Blahdey Blah Performance Test as the <H1> topic title. So when I use an <xref> to reference that topic, it comes out as "Please refer to the Blahdey Blah Performance Test for more information." Which is fine for this instance.

However, there are instances where I only want the Blahdey Blah part of the title and I don't want to include the words "Performance Test". For example, I also have a topic where I show the entire list of performance tests in the order they should be performed. In that case, I don't want to keep repeating "Performance Test" in each test title in the list. But if I use an <xref>, the complete title including "Performance Test" comes through.

This is how I want my list to look:
Perform the following performance tests in the order shown:
1. Blahdey Blah
2. Yada Yada Yada
3. And So On

But because the words "Performance Test" are part of the <H1> in the topic, this is how it looks using <xref>s:
Perform the following performance tests in the order shown:
1. Blahdey Blah Performance Test
2. Yada Yada Yada Performance Test
3. And So On Performance Test

I don't want the words "Performance Test" repeated every time. Is there a way to exclude part of the text in the <H1> when using it for an <xref>?
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How can I customize an <xref> output?

Post by Nita Beck »

Your description of what you want to achieve is a perfect use case for using hyperlinks, not cross-references. By design, the text of cross-references' text is meant not to be edited. Rather, when it builds output, Flare will use the first heading in a destination topic as a cross-reference's text. The only thing you can change about cross-references is their format. For example, you could have an xref that'll render in online output as "See Title of Your Topic". The same xref rendered in print output could be "For more information, see 'Title of Your Topic' (on page 33)".
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
luvthepug
Propeller Head
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Post by luvthepug »

By design, the text of cross-references' text is meant not to be edited. Rather, when it builds output, Flare will use the first heading in a destination topic as a cross-reference's text. The only thing you can change about cross-references is their format.
Thanks, Nita. I was afraid of that. I really wanted to be able to use the <xref> in this case because the test names can change, and to have the auto-update feature of the <xref> is very helpful when that happens.
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: How can I customize an <xref> output?

Post by ChoccieMuffin »

Just looking at it from a different direction, do you HAVE to have "Performance Test" in the headings for each of those items? You could rephrase the text around your x-refs to say something like "refer to the Blahdey Blah performance test for more information" where just the bold underlined text is the topic heading. Obviously you'd have to include "Performance Test" in whatever surrounds your x-ref, but it's very manageable, and would mean your x-refs would keep up to date if titles change. (As a tip I don't ever include "For details see" or similar in the x-ref format because I like to be able to expand a bit, which you can't if you've included that gubbins in the x-ref format.)
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
luvthepug
Propeller Head
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Post by luvthepug »

Just looking at it from a different direction, do you HAVE to have "Performance Test" in the headings for each of those items?
Yes, unfortunately those titles do need to include the text "Performance Text" in them because there are instances where there is the same name but as an adjustment topic. So there could be both "Blahdey Blah Performance Test" and "Blahdey Blah Adjustment" topic pages. So I do need to include "Performance Test" (and similarly "Adjustment") in the topic titles to distinguish the two topics. (And I don't include any additional text in my <xref> formats...probably my example was misleading.) But thanks for tip anyway.
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: How can I customize an <xref> output?

Post by ChoccieMuffin »

luvthepug wrote:
Just looking at it from a different direction, do you HAVE to have "Performance Test" in the headings for each of those items?
Yes, unfortunately those titles do need to include the text "Performance Text" in them because there are instances where there is the same name but as an adjustment topic. So there could be both "Blahdey Blah Performance Test" and "Blahdey Blah Adjustment" topic pages. So I do need to include "Performance Test" (and similarly "Adjustment") in the topic titles to distinguish the two topics. (And I don't include any additional text in my <xref> formats...probably my example was misleading.) But thanks for tip anyway.
That sounds perfect - both the Performance Test topics and the Adjustment topics can have the same text as their h1 and you can handle x-refs in the text to them in the same way - "refer to the performance test Blahdey Blah on page xxx for more information" and "refer to the adjustment Blahdey Blah on page yyy for more information", with the two cross-refs pointing to the relevant topics (which, obviously, are two different topics). The x-ref can contain the page number for printed output or just a link for online output, formatted in your different mediums. As you've already said you have a top-level book for performance tests, I'm guessing you may have another top-level book for adjustments, so even in your TOC if you use the automatic titles, things will still be clear.
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
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: How can I customize an <xref> output?

Post by doc_guy »

If you always want to have the text "Blahdey Blah" and never "Blahdey Blah Performance Test" you could use the title attribute. I think that is what MadCap will use for the cross reference unless you specifically point to the H1, or if no title attribute is present.
Paul Pehrson
My Blog

Image
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: How can I customize an <xref> output?

Post by Nita Beck »

Doc_guy: <headslap>Doh! Of course!</headslap>.
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
luvthepug
Propeller Head
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Post by luvthepug »

If you always want to have the text "Blahdey Blah" and never "Blahdey Blah Performance Test" you could use the title attribute.
(Sorry, I'm tardy in getting back to my post to check for replies.)
doc_guy, I'm not familiar with using attributes. How would I go about using that feature to accomplish what I want in my scenario?
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: How can I customize an <xref> output?

Post by doc_guy »

In the Content Explorer, right-click on a topic, and select Properties. You see this dialog box:
Image
Enter the title you want to use in the Topic Title box. This will then be used for cross references, breadcrumbs, TOC entries, and entries in the menu proxy.
Paul Pehrson
My Blog

Image
luvthepug
Propeller Head
Posts: 22
Joined: Thu Jun 23, 2011 8:06 am

Re: How can I customize an <xref> output?

Post by luvthepug »

Ah, OK, since you had referred to it as an "attribute" I was looking in the Attributes Window where there is a setting for "title". I've never done anything in that window. I will try doing it in the file Properties window. Thanks very much doc_guy!
doc_guy
Propellus Maximus
Posts: 1979
Joined: Tue Nov 28, 2006 11:18 am
Location: Crossroads of the West
Contact:

Re: How can I customize an <xref> output?

Post by doc_guy »

Happy to help! Hope it helps you get to where you want to be.
Paul Pehrson
My Blog

Image
Post Reply