Should Madcap merge Cross References and Hyperlinks?

[iand]

I've had quite a few problems deciding between hyperlinks and cross references and wasted a fair amount of time on each. My latest solution has involved a mixture of both along with conditional text, it's fairly messy and I'm not looking forward to maintaining it.

The differences between cross references and hyperlinks are quite subtle and seem to trip a fair number of people up. If you make the wrong choice then you end up having to convert every instance to the other type by hand. To my mind these are just two sides of the same coin. Personally, given the importance of cross references in technical writing, I think Madcap should update cross references to support all the features of hyperlinks such as "link text" and scrap hyperlinks for the next version of Flare. I thought I would see what other people thought. Is this a good use of Madcap's development time? If other people agree then I will raise a bug and encourage others to do the same. I also think it should be possible to use context sensitive cross reference styles which vary based on the conditions set for this output target and whether it was in the middle, beginning, or end of a sentence, within an li tag, on its own in a p tag without any accompanying text, etc. This would help me cut down on the use of conditional text, and the number of different xref styles I seem to need, the combinations can multiply quickly!

[KevinDAmery]

I could certainly see adding some additional features to XRefs to allow them to behave a little like HRefs (for example, giving users the option of specifying the link text rather than only referencing the text in the target paragraph). There is definitely room for enhancement there.

However, you wouldn't be able to remove Hrefs, because the Href is a basic part of XML and HTML. One of Flare's selling features is that it generates compliant XHTML (unlike good ol' RH that litters custom tags all over the place), and doing something to prohibit Hrefs would break that compliance and make it a proprietary output. Doing anything proprietary would be a step backwards, imo. (Besides, can you imagine the marketing grief Madcap would get if someone posted on HATT or TechWRL that "in version X of Flare it actually tells me that <a href="blah"> is illegal! What kind of HTML editor is that?!" Definitely not the way to win market share....)

[beagley]

I, too, found the differences between these two concepts confusing. There's plenty of overlap.

In the end, I scrapped CRs, and I only use hyperlinks.

We will always need hyperlinks... because we'll have plenty of things OUTSIDE of our project (and indeed, outside our company) that we need to link to. So I can't see ditching hyperlinks for CRs.

I found the odd constrictions of CRs too annoying.

[mattf]

I use hyperlinks in my WebHelp for the list of topics in the intro to each chapter, and for links to external documents (readme's, etc.).
I use cross-refs for everything else, because it's so easy to have "on page x" added for print outputs.

It never occurred to me I could use cross-refs for my chapter intro links as well, but I already have a style for the links set, so it's a really easy workflow and I probably wouldn't change it.

[iand]

We will always need hyperlinks... because we'll have plenty of things OUTSIDE of our project (and indeed, outside our company) that we need to link to. So I can't see ditching hyperlinks for CRs.

Good point, but this could easily be fixed by adding a field to the insert cross reference dialog where you can add the link URL.

However, you wouldn't be able to remove Hrefs, because the Href is a basic part of XML and HTML. One of Flare's selling features is that it generates compliant XHTML (unlike good ol' RH that litters custom tags all over the place), and doing something to prohibit Hrefs would break that compliance and make it a proprietary output. Doing anything proprietary would be a step backwards, imo. (Besides, can you imagine the marketing grief Madcap would get if someone posted on HATT or TechWRL that "in version X of Flare it actually tells me that <a href="blah"> is illegal! What kind of HTML editor is that?!" Definitely not the way to win market share....)

Not sure I understand Kevin, as cross references i.e. xrefs tags always contain Href attributes. I assume cross references become <a> tags with href attributes in webhelp output? He says optimistically . I guess they are not standard inside the XHTML files Madcap creates for each topic but there are lots of tags like that e.g. condition tags, etc.

Except for the link text I can't see anyway in which cross references are different from hyperlinks. We would need something called {linktext} like {title}, {page}, etc.

Anybody got any more ideas why hyperlinks couldn't be merged into xrefs

[forfear]

I use hyperlinks when I am embedding a link within a paragraph by linking a word to a specific topic of interest.
I use cross references when the link and the title of the topic it is referring needs to stand on its own. Usually a cross-reference can sit comfortably on its own line or in a bullet point list.

A hyperlink will not.

Cross-references are also helpful. See Cross-references [Online]
Cross-references are also helpful. See "Cross-references" on page 11. [print]

Its not a choice of which is better. Its a choice of when which is appropriate.

[iand]

I use hyperlinks when I am embedding a link within a paragraph by linking a word to a specific topic of interest.
I use cross references when the link and the title of the topic it is referring needs to stand on its own. Usually a cross-reference can sit comfortably on its own line or in a bullet point list.

A hyperlink will not.

Cross-references are also helpful. See Cross-references [Online]
Cross-references are also helpful. See "Cross-references" on page 11. [print]

Its not a choice of which is better. Its a choice of when which is appropriate.

This is a very late reply. Anyway, I really like these examples, this is more or less how I am using cross references and hyperlinks at the moment. However if you link a word to a specific topic of special interest then you don't have the option of doing the following:

A hyperlink - see page 31 for more details - is used to link a word to a specific topic. [print]
A hyperlink is used to link a word to a specific topic. [online]

If cross references supported link text perhaps using a keyword {linktext} then I think this could be done with cross references and two different cross references classes. Once cross references support link text then I can't see any further reason to keep hyperlinks. The advantage being that we gain flexibility and we could also do away with the complexity of two very similar concepts. I think, currently, my example above can only be done using conditional text and a hyperlink and a cross reference to the same topic.

[mattf]

I may not be following this accurately, but the way I do the above doesn't require conditions. I have a single cross reference style that has different displays for print and web, determined using the print and non-print media. For print, the style includes "on page {page}".

So for me it looks like this:
Print -- I don't have any need for conditional text (see "Conditional Text" on page 17).
Web -- I don't have any need for conditional text (see "Conditional Text").

[Andrew]

I may not be following this accurately, but the way I do the above doesn't require conditions. I have a single cross reference style that has different displays for print and web, determined using the print and non-print media. For print, the style includes "on page {page}".

So for me it looks like this:
Print -- I don't have any need for conditional text (see "Conditional Text" on page 17).
Web -- I don't have any need for conditional text (see "Conditional Text").

Yes, this is exactly how I do it. Unless you need an actual hyperlink (i.e., you need text in a sentence to display with a link, rather than the text of the xref target), there is little reason to use hyperlinks at all -- though they are slightly easier to use if you are producing purely online help.

[mattf]

Well, this is interesting. I never really thought about it in a metacognitive way, so I can't really retrace my thinking here. I use cross-refs as I noted above, for linking from paragraphs of running text, but I use hyperlinks if I'm going to do this:

Click any topic below for further information.
This
That
The other thing

And yet, I couldn't really tell you why I do this. I suppose I could just use a cross-ref. I think the reason is because before I ever figured out cross-refs I created a hyperlink style called topicListIndent that I'm still using in my help. Maybe I didn't feel like recreating that style as a cross-ref style.

[lauraj]

Hm, I always found it conceptually simple, but I don't use the two constructs the way everyone else here does (since you don't all use them the same way ).

Cross-references get updated automatically to reflect the item they're linked to. For example, if I link to another topic and I want the link text to always be the same as the topic title *even if the topic title changes*, I use a cross-reference.

If I want total control of the link text (and don't want it updated for me), or obviously if I'm going outside the project, I use a hyperlink. So:

Paragraph text blah blah blah this concept utilizes the Frammajam construct more para text <= That's a hyperlink. I want my sentence to say "Frammajam concept" regardless of whether the linked topic is named "Using a Frammajam", "About the Frammajam", or "Useful things to know".

But then I'll use:

See Also:
- About the Frammajam <= That's a cross-reference. Next month, it may say "See Also: Using a Frammajam". I want it that way because it's confusing to click the "About" link and land in "Using".

Of course, I also have reams and rafts of help that uses hyperlinks where it ought to use xrefs. That's the stuff that originally came from RoboHelp.

[mattf]

Oh, yeah. Right. Thanks Lauraj. This is what I do, too. I knew there was a reason that I used them for different things. It's just as you say. You sometimes want the text to reflect the reality at the other end of the link, and sometimes you just want it to hold its ground. Thanks for the reminder. For this reason I would vote NO on merging these.

[iand]

Hi Mattf, Lauraj

Thanks for your comments. Just to make clear, I am not proposing that hyperlinks and cross references should be merged as they are currently. I am suggesting that cross references should be updated to support modifiable link text, external urls, and variables i.e. the features hyperlinks currently have that cross references don't support. I think this is a fairly simple update. Once that has been achieved perhaps hyperlinks could be retained but discouraged. Madcap could then enhance cross references further without having to add any new features to hyperlinks. I guess we would also need a tool to convert hyperlinks to the new style cross references.

I hope that this would simplify situations like the following which are tricky to rectify:

Of course, I also have reams and rafts of help that uses hyperlinks where it ought to use xrefs. That's the stuff that originally came from RoboHelp.

And allow you to do things like:

1. A [b]widget[/b] - see page 31 for more details - is used for blah blah. [print]
2. A [b]widget[/b] is used for blah blah. [online]

Currently example 1 is not possible if you want to choose the text to replace widget (link text) instead of using the title, heading, etc. of the linked topic.

[KevinDAmery]

I would be fully supportive of enhancing XREF behaviour to allow you to edit the link text, to include variables, and to do anything else you could do with HREFs. I would not be supportive of anything that would change how HREFs work.

[Andrew]

Hm, I always found it conceptually simple, but I don't use the two constructs the way everyone else here does (since you don't all use them the same way ).

Cross-references get updated automatically to reflect the item they're linked to. For example, if I link to another topic and I want the link text to always be the same as the topic title *even if the topic title changes*, I use a cross-reference.

If I want total control of the link text (and don't want it updated for me), or obviously if I'm going outside the project, I use a hyperlink. So:

Paragraph text blah blah blah this concept utilizes the Frammajam construct more para text <= That's a hyperlink. I want my sentence to say "Frammajam concept" regardless of whether the linked topic is named "Using a Frammajam", "About the Frammajam", or "Useful things to know".

But then I'll use:

See Also:
- About the Frammajam <= That's a cross-reference. Next month, it may say "See Also: Using a Frammajam". I want it that way because it's confusing to click the "About" link and land in "Using".

Of course, I also have reams and rafts of help that uses hyperlinks where it ought to use xrefs. That's the stuff that originally came from RoboHelp.

This is exactly what I was trying to say, but far more poorly.

[KevinDAmery]

Hi Mattf, Lauraj

Thanks for your comments. Just to make clear, I am not proposing that hyperlinks and cross references should be merged as they are currently. I am suggesting that cross references should be updated to support modifiable link text, external urls, and variables i.e. the features hyperlinks currently have that cross references don't support. I think this is a fairly simple update. Once that has been achieved perhaps hyperlinks could be retained but discouraged. Madcap could then enhance cross references further without having to add any new features to hyperlinks. I guess we would also need a tool to convert hyperlinks to the new style cross references.

Ok, but how do you handle the second situation that Laura described, namely where she wants the link text to change if the title of the topic it's linked to changes? There needs to be some way to handle both approaches. If you make XREFs have editable link text, then it removes the ability to have the link be whatever the target topic title is at build time - that capability makes sense if you have a lot of documentation and manually updating all the hyperlinks to have the proper link text would be, ahh, time consuming. (And it's even more important in multi-writer setups where Writer One changes the topic title and Writer Four doesn't realise all her links need to have their link text updated.)

You could do something with a user selecting in the XREF setup, but that might get cumbersome. I'd have to see how it worked to make a judgement.

My biggest problem with XREFs (which I believe I mentioned before) is that if you have a Variable in the title of the linked topic it doesn't resolve into the link text. If they could solve that, I'd be happy. Any extra functionality over and above that would be bonus points.

[lauraj]

You could do something with a user selecting in the XREF setup, but that might get cumbersome. I'd have to see how it worked to make a judgement.

Right, I can envision a control (well, two controls) wherein you select either an xref format, or a static user-defined text string. I agree that it feels a bit cumbersome. It basically amounts to a radio button with choices "act like an xref" or "act like a hyperlink". The only advantage I see in merging the two constructs is that it would be easier to change a reference from one to the other, which I've occasionally needed to do.

My biggest problem with XREFs (which I believe I mentioned before) is that if you have a Variable in the title of the linked topic it doesn't resolve into the link text. If they could solve that, I'd be happy. Any extra functionality over and above that would be bonus points.

Ooh yes, that drives me nuts! I consider it a bug, though I've never submitted it as such.

[KevinDAmery]

You could do something with a user selecting in the XREF setup, but that might get cumbersome. I'd have to see how it worked to make a judgement.

Right, I can envision a control (well, two controls) wherein you select either an xref format, or a static user-defined text string. I agree that it feels a bit cumbersome. It basically amounts to a radio button with choices "act like an xref" or "act like a hyperlink". The only advantage I see in merging the two constructs is that it would be easier to change a reference from one to the other, which I've occasionally needed to do.

That's more or less where I'm at as well. However, if done right you could get some nifty things - such as the ability to manually set the XREF text but include dynamic page references (I believe Ian mentioned this possibility earlier in the thread). If that could be done in an easy-to-use way, it would give us the best of both worlds.

My biggest problem with XREFs (which I believe I mentioned before) is that if you have a Variable in the title of the linked topic it doesn't resolve into the link text. If they could solve that, I'd be happy. Any extra functionality over and above that would be bonus points.

Ooh yes, that drives me nuts! I consider it a bug, though I've never submitted it as such.

Oh, please do submit it. Madcap have told us that the more people who report an issue the higher priority it is, so everyone who considers this a bug should let'em have it

[iand]

Hi Kevin, LauraJ

Personally, all I think you need is a text box in the Create Xref window which allows you to enter "link text", I'll call this the link text field. Then we could add a {linktext} command to the list of commands like {title},{page}, etc. that we already have for xref classes. The {linktext} command would then be replaced with whatever had been entered in the link text field. Changing an xref to a "hyperlink like xref" would then be a simple matter of changing the xref class for that particular xref. I could also then create xref classes like {linktext} on page {page} which is impossible to do with hyperlinks.

If you want a xref which updates when the title of the topic changes you just use {title} in the xref class.

Oh, I totally agree that the highest priority is getting the variable bug fixed for xrefs. Actually, I think maintaining two similar concepts makes it harder for Madcap developers with the result that there are more likely to be bugs. I wouldn't be surprised if they forgot to add support for variables to xrefs when xrefs were added but did add them to hyperlinks

Ian

[KevinDAmery]

Well, it is a lot simpler with hyperlinks because the link text is embedded in the topic, meaning the Variable code can work exactly as it does in the rest of the topic tags. By comparison, in an XREF the link text is generated during the build process - so the programming involved in implementing Variables would perforce have to be different.

However, that doesn't excuse the fact that they had XREF's working at least as far back as version 2.0 but here we are in version 5.0 and they still don't support Variables. (And yet someone thought that building an instant messenger client into Flare was a useful addition. )

[iand]

Well, it is a lot simpler with hyperlinks because the link text is embedded in the topic, meaning the Variable code can work exactly as it does in the rest of the topic tags. By comparison, in an XREF the link text is generated during the build process - so the programming involved in implementing Variables would perforce have to be different.

Good point.

However, that doesn't excuse the fact that they had XREF's working at least as far back as version 2.0 but here we are in version 5.0 and they still don't support Variables. (And yet someone thought that building an instant messenger client into Flare was a useful addition. )

It's kind of shocking that they haven't fixed this since version 2.0. I'm not sure they should be concentrating on DITA and producing Teamserver when basic bugs like this are still present! The instant messenger client makes me laugh, what were they thinking

[Nita Beck]

I've been reading this topic with interest as it unfolds.

I too use hrefs for those links whose link text I want to control and xrefs for links those link text I want to match their xref-ed topic titles.

But I am confused when I read that xrefs don't support variables. They don't??? Then how is it that in my PDF output and my WebHelp output, I've got xrefs that point to topics that have variables in them and those xrefs all resolve just fine? What is this bug that several of you have spoken of? I do not see any such bug. My xrefs to topic-titles-with-variables work as I expect them to work...

Am I missing something here?

Nita

[KevinDAmery]

Hmmm... it has been a while since I tried this, maybe they fixed it. I'll have to give it a whirl.

[forfear]

My response to this post is...

No.

Cross-references and hyperlinks may both do the same thing, link you to other documents (or parts of documents).

But they both serve different types of linking mechanisms for different mediums.

[iand]

But they both serve different types of linking mechanisms for different mediums.

Hi forfear,
I guess I would argue that this is historical due to the current limitations of xrefs and that the better place to handle different linking mechanisms is by enhancing xrefs and using different xref classes for different linking mechanisms. You could also use different xref classes to provide different behaviour in different mediums.

Perhaps a good compromise would be to retain hyperlinks but enhance xrefs to support editable link text. I guess this would satisfy everyone?

Ian