Using Map Files / Map IDs

[Tech_Writer_KC]

Heya,

RH9, merged webhelp

I'm trying to set up Map IDs for a quasi-context sensitive help feature, and I'm feeling a bit overwhelmed. I've read through the RH9 help which links to the Grainge website and a couple more links, but I'm still not sure what to do.

First, the background:

We auto-generate a set of release notes for new features and fixes. This is done using a script that pulls the relevant information out of Dovetail (basically where all our support and development cases are stored). So basically our release list shows the case number, the area of the software, and a brief summary of the fix/feature. The release notes are script-generated as an .html file that we can link to in help.

The issue is that they want me to alter the release notes so that the case number serves as a hyperlink to the relevant topic in help. So, for example, if we had a new feature for widget making, case number 12345, the release notes entry for this would have a hyperlink that would take the user to the 'Widget Making' help topic.

My thinking is that I can use the case numbers as Map IDs, ie assign Map ID '12345' to the 'Widget Making' topic, and then create a generic link in the release notes that can 'insert' the relevant case number when the user goes to find that associated help topic.

Potential Issue:

We use a merged help system, but we do not need to merge map files. Our help system consists of one mostly-empty parent project (title page, about page, etc.), a project that contains the majority of our topics, a project that contains database information for technical users, and a few other odd projects. All of the linked topics are going to be in the same main child help project. Because of this, the map file/IDs are going to be a single set in a single project, but not the parent project.

Does this only affect the pathway for the basic link (e.g. "webhelp/mergedProjects/child1.htm" instead of "webhelp/start.htm"?), or are there other considerations? For example, the merged help map ID topics I've seen talk about using number ranges to denote the different projects, but since we've only the one, do we really need to do that? To me, it seems like we should be able to use a relatively straight-forward single-project type link, with the only difference being that the the link goes to a child project folder and not the main webhelp folder.

So far in testing, the link doesn't work, so I'm wondering if either the URL is not as straight-forward as I hoped, or I'm missing something else due to the nature of how our webhelp is set up. Because it's a child, do we still need to 'merge' map files even if we don't need one for the parent? (ie we create an empty parent map file, merge it with the child, and link to the parent?)

Thanks for any tips/advice!

[Peter Grainge]

If I have read this correctly there is a topic in a child project for each note. Why not use the file name as part of a URL?

If the topic was 12345.htm the call would be

pathto/startpage.htm#mergedProjects/childprojectfolder/path_in_childproject/12345.htm

With the degree of automation you have I am assuming you could create the filenames that way and as it is a rigid formula that your developers can do something similar.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Tech_Writer_KC]

Our help system is installed locally by many of our customers (some customers' remote sites don't have strong/consistent or any internet access), so the full pathway will vary - could your suggestion still work in that context? Would it require the full URL (won't work) or only relational to the Webhelp folder (would work, since the path within the Webhelp folder would never change, regardless of where the system's installed).

I think we could automate a generic path using the naming convention you suggest, but it would only work if the URL did not require the full path, as that would break for customers using a non-standard install of the help.

[Peter Grainge]

The relative path from the application to the help should be sufficient.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Tech_Writer_KC]

We're still working on trying to get Map IDs to work, and had a few more questions after using this topic:

http://www.grainge.org/pages/authoring/calling_webhelp/using_map_ids_merged.htm

We've gotten to the point where the hyperlink we create calls the child project (and displays its default starting topic), but doesn't go to the actual linked topic (ie the one with the Map ID associated with it).

1. I went ahead and did the 'merging' of Map files into the mergedProjects directory of the parent project. The .h file in the parent has a single range defined, since it only needs to point at a single child file. My understanding of the topic above is that the parent project .h only has the range - does it also need the individual map IDs listed in the child .h file too? Fex, right now since we're testing we only have a single Map ID set up, 12345. This is defined in the child .h file, does it also need to be added to the bottom of the parent .h file too (after the range defined entry)? Similarly, does each child .h file need the relevant range define line in itself, or is that just a parent entry?

(Basically, I'm confused by the language and example in Step 6 - the language makes it sound like all the individual IDs should be in there, but the examples only show the define lines).

Right now, our files look like:

Parent: #define child.htm 10000

Child: #define 12345 1

Does it need to be more like this?

Both parent and child (since we're not actually merging multiple map files, they should look exactly the same?)

#define child.htm 10000

#define 12345 1

2. The topic linked above states that there's a CSH test tool available from the RH Tools menu. I've looked through all options and I'm just not seeing it. Has this been removed or renamed? Nothing I see sounds anything like the tool mentioned. Again, we're in RH9.

Thanks,

[Willam_van_Weelden]

Hi,

When you use CSH in a merged project, the master project will automatically check all child projects when the context sensitive id cannot be found in the master project. Peter’s method includes merging the map files but I don’t think that is necessary. We have several merged projects that work perfectly without merging the map files. But Peter is the authority on merged help

It is important to first get the terminology straight. In WebHelp there are Map ID’s and Map numbers. The Map ID (or topic id) is an alphanumeric string that can be anything from one character to a hundred or more characters. Then there are the Map numbers. Map numbers are a number between 1 and 4.294.967.295.

The terminology is important because what RoboHelp calls a Map ID may be referred to as a map number. Reading the article on Peter’s site I get the impression that what is called a Map ID on Peter’s site is actually the Map number in RoboHelp. (Please correct me if I’m wrong Peter.) The Map ID in RoboHelp is the Topic ID on Peter’s site. See step 8 of the article, it describes how to create a test page using the default RoboHelp JavaScript API. But that test page actually uses the map numbers as the default JS API does not support topic id’s, only map numbers.

Your map file tells the following:

‘12345’ is the Map ID or topic ID.

‘1’ is the Map number. The Map ID referred to on Peter’s site if I’m not mistaken.

Calling the Map number 12345 will not work if you use the default method because you are looking for the wrong number. Try the following:

Say that your master project is placed on http://localhost/newproject.htm. Open a new browser window and add the following URL in the browser where you replace the url with the url your project is placed:

http://localhost/newproject.htm#<str=12345

Does this get the desired result? Also try the test page but use ‘1’ instead of ‘12345’. Does this also get the correct page?

You (or your developers) may also be interested in my WebHelp CSH dissection: http://www.wvanweelden.eu/robohelp/webhelp/csh Note that this article is aimed at developers and does not provide any direct answers, but it will help you understand the different settings in RoboHelp.

Hope this doesn’t confuse you and I hope my assumptions about your intended action are correct.

Greet,

Willam

[Captiv8r]

Hey there

Interesting post to say the least. I'll be interested to see if anyone posts a solution for that as it's a mind number of an issue with the Merged help and all.

What I am posting about is to say the CSH Test tool should be found in your Toolbox pod. ( View > Pods > Toolbox )

Good luck! Rick (who is very glad he isn't in your shoes at the moment)

Helpful and Handy Links RoboHelp Wish Form/Bug Reporting Form Begin learning RoboHelp HTML 7, 8 or 9 within the day! Adobe Certified RoboHelp HTML Training SorcerStone Blog RoboHelp eBooks

[Tech_Writer_KC]

Hmm...I may be an idiot, Rick!

Peter, in your example:

#define child1.htm 1000
#define child2.htm 2000
#define child3.htm 3000
#define child3a.htm 3001
#define child3b.htm 3002

What exactly are these lines referencing? When I first read through the topic, I thought you were using these to define # ranges - i.e. the first line means any four-digit number in the 1000s points to something in a project named 'child1.htm'.

But...are these meant to be sample lines similar to the one we've been testing with?

#define 12345 1

IE...is the '1000' in the first line meant to indicate the beginning number of a range, or a specific Map ID / Map Number being assigned?

[Peter Grainge]

Not MY method. You will see in the What's Covered section of that article that it was written by Greg Minter and that I have stated it is not a method I use.

The numbers look like the IDs that Greg used.

---

See www.grainge.org for RoboHelp and Authoring tips

@petergrainge

[Willam_van_Weelden]

Whoops, I'll be more careful. Good that you agree about the terminology, it will help if we're all talking about the same thing.

Greet,

Willam