CSH - Developer using alias.xml but. . . .

This forum is for all Flare issues not related to any of the other categories.
Post Reply
leep
Propeller Head
Posts: 29
Joined: Tue Nov 29, 2016 11:07 am

CSH - Developer using alias.xml but. . . .

Post by leep »

There may be many more things wrong with my project than the upshot of what I'm stating implies, but here is the case: My developer uses the generated alias.xml file to hook help topics to screens within our product. This has been working, more or less, right along, but not recently. I had MadCap Support help me sort out some issues, and now it seems that CSH is working perfectly WITHIN Flare. However, when I generate help, the generated alias.js file perfectly matches the combination of help topic, alias, and resolve ID set up in Flare, but alias.xml is radically and absurdly different. For example, one of the topic-alias combinations has an ID number of 1001 within Flare. In the generated alias.xml file, the same combination has the absurd resolve ID number -2147483648! Apparently, Flare is generating this absurdity on the fly, but why? And if this happens regularly and can't be overcome (a Flare bug? a feature?), can, and should, the developer be using the alias.js file instead to hook up CSH? And if so, how is that possible? Or, on the other hand, is Flare acting up tremendously for some reason, and this is not the way things should work and I should, therefore, rely on MadCap Support for help out of this dilemma? Thanks for any answers you can supply.
leep
Propeller Head
Posts: 29
Joined: Tue Nov 29, 2016 11:07 am

Re: CSH - Developer using alias.xml but. . . .

Post by leep »

So I'm replying to my own post. That's because I solved the problem through a day-long effort. The issue was competing alias and header files in the project. Even though I told Flare which header file to use with the alias file, it went haywire during a build, apparently conflating the contents of the additional header files and generating absurd, random values in the output alias.xml file.

Two questions: 1. Who wants to confess that something like this has happened before to them when working with Flare? 2. Who has witnessed this "feature" in Flare: Even if you try to delete some files, they still show up in the project, sometimes without your even needing to close the project, say, for example, after you do a build of help? If you can answer "yes," to either or both questions, welcome to the club. I'll give Flare Support a piece of my mind for you.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: CSH - Developer using alias.xml but. . . .

Post by NorthEast »

Just as a note, I don't think you can tell Flare which header file to use with the alias file.

When you open an alias file/editor, it displays the identifiers/values from all your header files in the project.
So it's showing you every identifier that you can link to a topic, but these aren't saved in the alias file itself until you link an identifier to a topic. So it only saves that mapping information in the alias file.

You can select a header file in the alias editor, but the purpose of that is only to (a) filter the list, (b) tell Flare which header file to add new identifiers to.

So your issues could possibly be due to problems in the header files, so maybe check those for duplicate identifiers, bad values, etc.
leep
Propeller Head
Posts: 29
Joined: Tue Nov 29, 2016 11:07 am

Re: CSH - Developer using alias.xml but. . . .

Post by leep »

Thank you for that information about how the alias editor works, Dave. I'll remember that. Still, I didn't know that additional header files in the project could result in such crazy and catastrophic results as I've described. I would suggest that this issue get a red-letter call-out in Flare online help. And if MadCap wants proof of what can happen, well, I have documentary evidence I would gladly share.
jimgilliam
Propeller Head
Posts: 81
Joined: Tue Jun 04, 2013 9:49 am
Location: Arkansas, U.S.A.

Re: CSH - Developer using alias.xml but. . . .

Post by jimgilliam »

Dave Lee wrote:Just as a note, I don't think you can tell Flare which header file to use with the alias file.
Hi David. I think you can set a primary header file for individual alias files to use. It's in the Identifier Options dialog (open the alias file and in the local toolbar, click Identifier Options) and set the Primary Header option with the header file of your choice.

Anyway, this help topic may be useful for this thread: https://help.madcapsoftware.com/flare20 ... y%20header

Question: I can't use a hashtag in the alias file editor as a topic ID, but I can in the header file. If those two topic IDs don't match, does the system default to the numerical value to open the associated topic file?

My issue is, I've converted from Tripane layout to TopNav and that equals dead links in the application that uses my CSH links. Tripane example is ...index.htmt#topicFileName and TopNav does not use this format.

I don't want the developers to have to change the old Tripane links, so I thought the alias file might work so I could do the work on my end? Like a URL redirect sorta?

What are your thoughts?
:flare:
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: CSH - Developer using alias.xml but. . . .

Post by NorthEast »

jimgilliam wrote:My issue is, I've converted from Tripane layout to TopNav and that equals dead links in the application that uses my CSH links. Tripane example is ...index.htmt#topicFileName and TopNav does not use this format.

I don't want the developers to have to change the old Tripane links, so I thought the alias file might work so I could do the work on my end? Like a URL redirect sorta?

What are your thoughts?
What is the exact format of the links to your Tripane output, and what doesn't work now?

Looking at your example index.htmt#topicFileName - were you previously using the direct path and filename for the topics, and not using identifiers/values?
If you were, then a link like index.htm#topic.htm will still work fine for TopNav as well as Tripane - that has not changed

Anyway, if you're going to use identifiers/values in the CSH, then you need to change the links to use the format: index.htm#cshid=xxx
If so, then presumably the developers need to change the link anyway, since you're moving from using the filename to an identifier/value.
jimgilliam
Propeller Head
Posts: 81
Joined: Tue Jun 04, 2013 9:49 am
Location: Arkansas, U.S.A.

Re: CSH - Developer using alias.xml but. . . .

Post by jimgilliam »

Thanks for the information, Dave. I did not know Flare automatically redirected URLs in that fashion. I thought because the TopNav URLs were visibly different than the Tripane URLs, we would have to create the header/alias files and have the devs change many links in the application.

Yes, Dave, we're using the filename method because the app was initially built that way. I wanted to save our devs some time/work. We've tested several projects using the Tripane links with TopNav and it does work, so thank you for that valuable info that I didn't know about Flare!
:flare:
devjoe
Sr. Propeller Head
Posts: 337
Joined: Thu Jan 23, 2014 1:43 pm

Re: CSH - Developer using alias.xml but. . . .

Post by devjoe »

If you have header files in your project that you don't want Flare to use with a given target, set conditions on them to exclude those files. Since header files are not XML, the conditions will be stored in a .props file alongside the header file, but this works.

If you have header files in your project with conflicting numbers for the same alias, and those numbers aren't needed for any target, delete the numbers you don't want.

As was stated already, the choice of header file in the Alias editor is not a setting for the output. The reason this is there is to limit what is displayed in the alias editor to a particular header file and to control which header file any newly created CSH numbers go to. If you have multiple header files and use the default (all identifiers) selection in the alias editor, Flare won't let you specify numbers because it doesn't know which header file to write those numbers to. However, the (all identifiers) option is useful, because it lets you see where you have conflicts among different header files.
spatte22
Propeller Head
Posts: 18
Joined: Tue Jul 03, 2018 11:50 am

Re: CSH - Developer using alias.xml but. . . .

Post by spatte22 »

I'm experiencing an interesting situation relevant to header and alias files, plus issues around potentially needing multiple header files. I think that replying to this thread would be more ideal than starting a new one. Setting up and expanding CSH has been quite the adventure for me over the past year or 2, so hopefully the info will help someone else in the future ;). Also, hopefully someone more knowledgeable has an answer or 2 for me, ha.


Q: What is the purpose behind connecting an alias file with a target instead of a header file? Is this potentially a design flaw?
My understanding is that the main purpose of the alias file is for more user-friendly (basic) management of CSH IDs, but the header file essentially determines the basis of CSH functionality - see my use case below for an explanation of how I reached this conclusion. I meddled around in the alias files, target, and header files to see if there was a way to specifically associate an alias file with a header file, and I don't think there is. Also, as previously mentioned, the whole setup requires the alias file to be determined in the target (not a header file). Why?

Use Case:
This is how I realized my mistake and prompted the question above. My team generates 2 html5 targets from the same project. We set up CSH for 1 target (it's working great) and are working on the 2nd. I haven't paid much attention to the header file since I've so far been able to do all the work in the alias file; I haven't needed to touch the header file at all since you connect the alias file with the target. We will have a handful of already-existing IDs that will be used in the 2nd target, too (or rather, we'd need some IDs with the same naming convention for both targets). So, I created a 2nd alias file using the existing one as a template so all of the existing IDs would also appear in the new file since we will have some overlap of ID names - or so I thought that's what was happening (it was actually just the filter displaying all IDs from the single header file).
Then, I deleted from the 2nd file any ID that we did not need, and kept the "overlap". After doing so, I noticed that all of the IDs were broken in the 1st alias file.... which was odd and concerning. After some investigation, I found out/realized that when we deleted all of the not-needed IDs from the 2nd alias file, it also deleted those entries from the header file, which then broke the links in the 1st header file. Again, I hadn't paid attention to the header file at all since I could manage the IDs in the alias file and also connect the alias file to the target. Well, as you guys know, you can filter IDs in the alias file to display IDs from a specific header file. Since we only had 1 header file (at the time), that's why the unlinked ID entries displayed in the 2nd alias file.
OK... I realized my mistake and am now moving forward: what if I have a header+alias for 1 target and a 2nd header+alias for the other target? Yeah... that would be great, but I need to connect an alias file with the target, *not* the header file. So.... what do we do? Well, a decision has not been made, but so far I'm debating between using a different naming convention for the "overlapping" IDs for the 2nd target, or perhaps having 2 header files (one for each target) and conditioning them appropriately.

Thanks for reading my experience/mistake - which option do you think is best? Also, do you think that it's a design flaw to have the alias file connect to a target?
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: CSH - Developer using alias.xml but. . . .

Post by NorthEast »

The header file contains a list of the identifiers (or values).

The alias file contains only the links between the identifier (or value) and the topic.

You need to be able to choose the alias file for the target because different targets may need to use different identifiers, or the same identifier may need to be linked to a different topic.

If you use the same header file(s) for both targets, then in each alias file you only need to set up topic links for some of the identifiers, and ignore the other identifiers that aren't used for that target.

If you don't want to see identifiers that aren't used by that target, then consider splitting up the header file; e.g. (a) have separate header files for identifiers shared by both targets, and identifiers used only for a particular target; or (b) use a separate header file for each target. It just means you have to remember to select the header file in the alias editor, to see the identifiers for that target.
Post Reply