How do you include snippet heading as xref text?

This forum is for all Flare issues not related to any of the other categories.
Post Reply
devans
Sr. Propeller Head
Posts: 108
Joined: Thu Sep 09, 2010 9:56 pm
Location: Sydney Australia

How do you include snippet heading as xref text?

Post by devans »

I have some topics in my project that are entirely snippets. That is, the first heading of the topic is included in the snippet. When I insert a cross reference to these topics, the hyperlink just shows "_" without the topic heading, although it does link to the correct topic if you click it. I tried typing in the topic heading between the inverted commas, but it gets lost when I build. I also thought that maybe I could insert a bookmark at the start of the topic, making the bookmark name the same as the first heading. However, when I go into the cross-references dialogue box, I can't work out how to make the cross-reference pick up the actual bookmark title.

Can anyone help with this problem?

Thanks.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: How do you include snippet heading as xref text?

Post by NorthEast »

The xref text is inserted at build time; although you can overwrite the xref text in the topic, it is just a placeholder and is not actually used.

I've just tried doing this, and it seems to work ok in the output. When I insert a xref to a topic containing just a snippet, the link displayed in the editor is blank. However, when I build the project, xref text in the output shows the heading from the snippet correctly.

So, for me at least, it is just the link text in the editor that is incorrect; it works ok in the output.
Andrew
Propellus Maximus
Posts: 1237
Joined: Fri Feb 10, 2006 5:37 am

Re: How do you include snippet heading as xref text?

Post by Andrew »

Yep, Dave's right; if the entire topic is a snippet, Flare should pick up the first header for your xref. Where it doesn't work so well is for lower headings. I've put a feature request into MadCap about this a while back.

If you can't get the first heading to work, I'd suggest contacting MadCap Support.
Flare v6.1 | Capture 4.0.0
devans
Sr. Propeller Head
Posts: 108
Joined: Thu Sep 09, 2010 9:56 pm
Location: Sydney Australia

Re: How do you include snippet heading as xref text?

Post by devans »

Thanks for your replies. Most of the headings in my snippets would be level 3 or 4, so it sounds like that's why it's not working.
devans
Sr. Propeller Head
Posts: 108
Joined: Thu Sep 09, 2010 9:56 pm
Location: Sydney Australia

Re: How do you include snippet heading as xref text?

Post by devans »

I've just realised what was causing my problem, because Flare was picking up the x-ref headings from some snippets but not others. I realised that it wasn't picking up headings because I had left the topic bookmark on the first line of the topic in a H3 or H4 style and inserted the snippet below. Thus, it was picking up the bookmark paragraph which was blank, while still linking to the correct topic. I have now removed the bookmarks and all is working perfectly.

Thanks again for your help.
Zerozeddy
Propeller Head
Posts: 45
Joined: Mon Dec 01, 2014 9:42 am

Re: How do you include snippet heading as xref text?

Post by Zerozeddy »

I am having a similar problem in 2018. I am putting an xref into a topic whose heading is a snippet, and it comes out missing. Before this r2 release (installed yesterday) I'd bodged it to work by adding a non-breaking space after the snippet in the target topic's heading. To make this work now, I have to add the same snippet after each xref.

<MadCap:xref href="../Path/folder1/target-topic.htm"><MadCap:snippetText src="../Path/folder2/header-that-goes-into-target.flsnp" /></MadCap:xref>

Picture the scope for error in maintaining these links, and time taken to create them in the first place when there are potentially 1000 of them in the documentation.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: How do you include snippet heading as xref text?

Post by NorthEast »

Note that the content inside the MadCap:xref is replaced when you build the project, so you're only affecting what you see in the XML editor, and it has no effect on the output.
So your solution is only as complex as you need it to be - you don't need to put the snippetText in there, you could put in any placeholder text that you want.

I appreciate it's a PITA that this issue exists in the first place though.
Zerozeddy
Propeller Head
Posts: 45
Joined: Mon Dec 01, 2014 9:42 am

Re: How do you include snippet heading as xref text?

Post by Zerozeddy »

Thanks - but when I tested it with

<MadCap:xref href="../Path/folder1/target-topic.htm">a</MadCap:xref>

the published result was

a

i.e. it still doesn't like topic headings that are snippets.

Have I misunderstood?
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: How do you include snippet heading as xref text?

Post by NorthEast »

It works fine for me. I have a topic that contains a snippet block (first thing inside the body), and the xref to that topic picks up the first heading h1 in the snippet (when I build the output). I can put anything I want inside the xref tag or leave it blank, and it looks fine when I view output.

Note you'll only see this in the output. You won't see it working in the XML editor or when you preview the topic.
Zerozeddy
Propeller Head
Posts: 45
Joined: Mon Dec 01, 2014 9:42 am

Re: How do you include snippet heading as xref text?

Post by Zerozeddy »

I appreciate you taking the time. Sadly my results are different here, irrespective of snippetry - any changes in the xref text persist after build. Perhaps I have a bug. I will continue to investigate...

Regards,
Andrew

**EDIT - it was pilot error. I'd conditioned out the topics that were linked. Ignore me.**
Post Reply