Link text replaced when h1 conditionalized out of XHTML outp

This forum is for all Flare issues related to PDF, eBook, Microsoft Word, Adobe FrameMaker, XPS, and XHTML book targets.
Post Reply
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Link text replaced when h1 conditionalized out of XHTML outp

Post by chuck_agari »

I find the most interesting bugs.

DITA topics do not contain headings or sub-headings. So in my failed attempt to produce DITA output, I conditionalized my h1 blocks in my topics to be excluded. And in an attempt to find an alternative to DITA output, I've been trying to see if any other output types will be acceptable to our partner. And I thought the "clean" XHTML might be an option.

But I was reviewing some of the topics in the output and I found a strange thing in a bulleted list of links: The link text to topics where the h1 was conditionalized out was changed to a block of text extracted from that linked topic. It seems that the extracted text was either the first heading-level block or the first block period.

For example, here is the original source code:

Code: Select all

<li>
                <MadCap:xref href="View_Alerts.htm">View Alerts</MadCap:xref>
</li>
And here is the code form the output:

Code: Select all

<li value="1"><a href="view_alerts.html" class="MCXref_0">Filter the Alerts List</a>
</li>
In this example, "Filter the Alerts List" is an h2 in the destination topic.

Here's another sample of original source:

Code: Select all

<li>
                <MadCap:xref href="Subscribe_to_Alerts.htm">Subscribe to Alerts</MadCap:xref>
</li>
And the code from the output:

Code: Select all

<li value="2"><a href="subscribe_to_alerts.html" class="MCXref_0">As an alternative to viewing alerts in Domain Protection, you can subscribe to any alert type. A subscription to an alert type will sent you an email whenever an alert is triggered of that alert type with the contents of the alert.</a>
</li>
In this case, the destination topic has no heading tags, so this is the content of the first p tag.

Never mind that the code is badly formatted or that a value attribue has been added (what's the deal with that, BTW?), what the heck is going on here?
jjw
Sr. Propeller Head
Posts: 133
Joined: Thu May 08, 2014 4:18 pm
Location: Melbourne

Re: Link text replaced when h1 conditionalized out of XHTML

Post by jjw »

That's not a bug - the default xref is configured to return {paratext} which is the text of the first block level element that it finds at the link destination. If you link to a file, that will typically be the h1 element except that you have removed the h1 element.

You can configure the xref style to return whatever you like (or better, set up your own xref styles for specific situations). For example, you could return the topic title (if set), or the file name.

https://help.madcapsoftware.com/flare20 ... ormats.htm
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Re: Link text replaced when h1 conditionalized out of XHTML

Post by chuck_agari »

jjw wrote:That's not a bug - the default xref is configured to return {paratext} which is the text of the first block level element that it finds at the link destination. If you link to a file, that will typically be the h1 element except that you have removed the h1 element.

You can configure the xref style to return whatever you like (or better, set up your own xref styles for specific situations). For example, you could return the topic title (if set), or the file name.

https://help.madcapsoftware.com/flare20 ... ormats.htm
Yup, I see what you're saying. My boss, who also used to be a tech writer and worked with structured content, reminded me that's how cross references typically work. What was bothering me here is that in the topic's source code, I was seeing explicit text between the xref elements, and I was expecting to see that text in the output.

I did a quick test of HTML5 output and saw the same thing. So I'm thinking that I'm going to have to rethink my notion of excluding h1 elements, which I had wanted to do to make the output more DITA-like.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Link text replaced when h1 conditionalized out of XHTML

Post by NorthEast »

chuck_agari wrote:What was bothering me here is that in the topic's source code, I was seeing explicit text between the xref elements, and I was expecting to see that text in the output.

I did a quick test of HTML5 output and saw the same thing. So I'm thinking that I'm going to have to rethink my notion of excluding h1 elements, which I had wanted to do to make the output more DITA-like.
The xref text is just placeholder text, and you'll notice it never changes from when you first inserted the xref. You can update the placeholder text in topics by using Tools > Update Cross-references. The placeholderhas no affect on the output, since the xref text is generated when you build the target.

If you want all your h1 titles to be hidden, but still want xrefs to work, then you could just use:

Code: Select all

h1
{
  display: none;
}
chuck_agari
Sr. Propeller Head
Posts: 225
Joined: Wed May 30, 2018 2:40 pm

Re: Link text replaced when h1 conditionalized out of XHTML

Post by chuck_agari »

I don't want them to be hidden. I want them excised from DITA output because the DITA DTDs do not allow headings. Basically, your DITA content is supposed to be chunked so that each file is the content under any one heading or subheading.

But Flare's DITA output is broken, so it's unusable anyway. I may have to begin again the tool search.
jjw
Sr. Propeller Head
Posts: 133
Joined: Thu May 08, 2014 4:18 pm
Location: Melbourne

Re: Link text replaced when h1 conditionalized out of XHTML

Post by jjw »

You could get rid of the headings with some kind of post-build processing. It wouldn't be too arduous if you automated it. That way the links would be generated before you removed the heading.

Or you could look for another tool :) I must admit that I sometimes wonder if the pros of Flare outweigh the cons.

J
Post Reply