Merging Webhelp via Peter Grainge'sMethod

[Phil_Wells]

Hi,

The company I work for has three seperate types of software. Lets call them Product A, Product B, Product C.

Most of the Help File modules are specific to a particular project. However, a few Help File modules are common to all three.

For example, I have a Definitions Help file that explains the terms used. (I use conditional build tags to filter the definitions that are specific to particular projects). This works fine when I merge HTML help.

I'm also producing merged Webhelp. This works fine with the modules specific to each project which are in the structure recommended by Peter. I can set up links between those files without difficulty.

However, I'm having problems with the links to the Definitions file. Because this is common to all three Products (A, B and C), it's not in the structure recommended by Peter. It's in a seperate directory at the same level in the directory structure as the 'child' files for (say) Product A.

The Definitions file appears in the TOC OK and you can navigate to it with no problems. However, I can't get links to work between the 'child' files and the Definitions file.

I've tried creating a dummy Definitions directory in the 'child' files and generating a Webhelp output there so I can link to the files I want to in the right location in the 'child' structure files . (And I've tried overwriting the generated files I wanted to link to with the origical .HTM files from the Definitions file so there's no java script in the file I'm trying to link to).

An obvious solution is to put a copy of the Definitions Help File into the directory structure for Product A, but that would defeat the original purpose of having a file common to all three projects - update the common file and the definitions are updated in Projects A, B and C similtaneously. Once I start using copies, I have to put a copy of the Definitions file into three locations to keep all the projects current with the modified Definitions file.

Is there any way of merging Webhelp with a situation like mine - files common to several Help Files (i.e common to Projects A, B and C)?

[Peter Grainge]

Did I say that any variations were permitted? :-)

Your problem is caused by some definitions being generic and some being specific. If they were all one type or the other, the options would be obvious.

You could try experimenting with this idea. Create a layout for all the children with Definitions being one of them, at this stage no build expression should be used with Definitions. Now generate Definitions alone but using each of your build expressions in turn. Each version should go to a different folder with a clear name. In the main merge experiment with substituting the different outputs from Definitions.

[Phil_Wells]

Hi Peter,

Thanks, you've helped me sort it.

The solution is to put a copy of the Definitions file into your 'child' file structure. You can then link to topics in this copy of Definitions. Otherwise, this file can then remain untouched.

Meanwhile, the original Definitions file can stay where it is and can have single source layouts set to give outputs where required; i.e. projects A, B and C. This means everytime I update the Definitions file, all projects associated with it get updated as well.

I did try making one bone-headed mistake which I'll mention to stop anyone else repeating it. I put the Defintions file into a sub-directory called Definitions_Copy in the 'child' file structure. This resulted in a broken link. It's got to be called Definitions just like the original version so RoboHelp gets the path right.

Other other thing I found you might consider for your snippets.

When you are setting up links into the 'parent' project, the menu that shows is dependent on what you've got the default single source layout set at. If (for example) you've got the default set to Webhelp, you won't see the remote topic option when you are trying to set up links in the HTML output. You have to set the default single source layout to HMTL to make the 'remote topic' option available.

Thanks....

[Peter Grainge]

That's not the way I create links. See the topic on merged webhelp which allows me to see all the topics without having to change the default output.

[Phil_Wells]

Peter,

I am setting up the links as per your website.

What I was also doing was setting up a project to generate both HTML and Webhelp outputs; hence I was swapping between default layouts.

Am I better actually setting up two seperate projects: Project A - HTML output and Project A - Webhelp ouptut rather than trying to make one project do both?

(Thanks for your help on this by the way).

[Peter Grainge]

Do that and you have two projects to keep aligned. Yuk!

The whole idea of SSL is to avoid just that. What you could do is take the structure I suggest but not use the redirect. Instead have some content but no links from that topic to a child. Then you have a parent that will work for both webhelp and CHM.

[Phil_Wells]

Hi Peter,

I've already set up one project in the way you suggest, and that's fine.

However, I got to thinking. With rare exceptions I keep my sub-modules fairly small and have an index as the default topic for that sub project. The links to topics in that sub project are then all internal from that index.

This means I have a master project with a master index. The master index links to all the sub-indexes, which in turn enables the user to call individual topics or groups of topcs.

I then have about 20 - 30 links per project to maintain between master index and sub-indexes.

Each sub project has got appropriate SSL's set up to send Webhelp files to the appropriate mergeProduct sub directories (as per your method) and appropriate SSL's set up to send .CHM files to the appropriate output directory for the HTML output.

Given that I'm already having to maintain two versions of each link between master index and sub indexes (Webhelp & HTML) and I'm batch generating Webhelp and HTML outputs from the sub-projects to the appropriate sub directories in the main project, I've started to wonder if there's any practical difference between having two types of output from one master project and having two versions of the master project so that one version generates Webhelp and HTML?

After all, once the master project is set up, the bulk of my updating comes from revising the sub projects. As long as I leave the sub index file name untouched, just regenerating the sub projects pretty well automatically updates the master.

I hear what you are are saying about the difficulty of keeping two projects aligned, but is there not a swings and roundabouts situation here?

I'm wondering that if a particular version of the project only outputs Webhelp or only outputs HTML, whether this will make it easier to tweak Robohelp to give optimum output for that output type. If it outputs both, will there be any conflict between optimum settings for the two different types of output? (A little bit out of my technical depth here to be honest).

I'm also thinking about printed output. My knowledge here is distinctly limited, but I know that you can print the whole thing off in one go from a HTML set-up, but you have to print the individual sub projects in Webhelp.

Is there any benefit from having a purely HTML output in terms of setting up printed ouput? (Thus far i've output printed documents, then had to spend a lot of time cleaning them up in Word).

[Peter Grainge]

Hi Phil

I wanted to think a bit on that.

You are, I believe, only talking about perhaps duplicating the parent and not the children. The options are:

1] One parent with no redirect in it but minimal content. You could have links to child projects but they will falsely report as broken. That parent would work for both CHM and webhelp.

2] One parent with a redirect. For webhelp that would require no changes but it would not work for a CHM output. If you simply remove the redirect you would leave the CHM user facing a blank page. That could be overcome with some minimal content and use of a build tag to exclude it from webhelp. However, the content would probably not sit comfortably with the content of what is otherwise your default topic.

3] Two parents as you propose. That does avoid having to remember to remove the redirect but you still have the issue of what content is in the single topic, bearing in mind the default topic, which is in a child using my method, already has that content.

For webhelp only, I prefer the redirect but for "dual users" such as yourself I think I would avoid the redirect and have a parent with one topic and no links or a minimal number. The latter will generate false reports of broken links but in this scenario that should be manageable. In other words, option 1. However, you are closer to what you need to produce so if two parents works better, I see no reason why not.

On printing, how are you able to create printed documentation in one go from an HTML setup? Are you perhaps talking about selecting a book in the online help and selecting "All topics"? If you are, have you looked at the formatting of the topics when printed that way?

You say you have to spend a lot of time cleaning up documents in Word. Some tidying up will be required for page breaks and table borders but that should not take long. What are the problems you have?

[Phil_Wells]

Hi Peter,

Thanks as ever for your prompt response.

Let me try and explain my problem in terms of explaining my company's software.

We start with Product A. This is designed to be used at the headquarters of a retail organisation. It's fairly complex software that carries out a number of sophisticated tasks.

We then have Product B. This is designed to go on a laptop or tablet, etc. It is a cut down version of Product A and can update some aspects of product A's database directly from the floors of individual stores via a wireless intenet link.

Product C can go onto any PC, lap top or tablet and produce reports from product A's database via an internet connection.

Product A ships with HTML help files as part of its installation.

Products B and C generally have their help files installed as Webhelp on a server and users of those products intenet connect with the server to read the help files. This keeps down the size of an installation on (say) a tablet.

To confuse the issue, some users like to have Webhelp for Product A and other users like to have the HTML files available for Products B and C.

This means I have to produce both versions of the help files for all three products.

Being new to technical authoring (I spent 30 years working as a metallurgist!) I did the first pass at the help files in RoboHelp for Word. I subsequently decided to switch to the RoboHelp for HTML environment as I believe it gives a better presented and more flexible output. I'm now in the process of transfering my help files from one environment to another.

In RoboHelp for Word thing were fairly simple - I wrote the sub projects, checked they were OK, then imported the Word file into the parent project. It just needed a bit of work rebuilding the appropriate section of the TOC and everything was fine.

In the RoboHelp for HTML environmernt (which i'm still learning), I'm having to think things through carefully.

Specifically, because I'm working in the dual HTML and Webhelp environments, I have to think carefully about my sub-projects. They have to be such that they can be built in both forms of output in the master project. This means I have to lodge my sub projects in the structure dictated by your Webmerge method and that I can't nest HTML sub projects, because of the need to use them in Webhelp ouputs.

I'm finding out that a bit of thought at the start can save me a whole lot of effort later in proceedings (which is why your help is so useful to me).

Going back to my original thoughs about whether to have a single master project that outputs both HTML and Webhelp or two slightly different master projects (one dedicated to HTML and one to WebHelp) I think I'll stick to a single master project at present. If I find i need need two master projects in the future, I can always take a copy and delete the parts I don't want.

As to cleaning up the printed documentation, one problem I have is that the entire document seems to come out as a single giant field. Click on one line and you select the whole document. No problems if you are supplying as hard copy, but it doesn't look good if you are supplying the Word document to the customer.

Another is that the topic headings seem to lose their formatting in pronted output. In the ccs they are Verdana, 12 point bold blue. In the output they are variable, for example Verdana, 10 point bold black in some cases, Verdana, 10 point black in others. Means I have to go through the whole document putting them back to what they should be.

Finally, I've just noticed a difference between the RoboHelp for Word and Robohelp for HTML environments - in the Word environment you can output the whole help file as a single printed document from the master project. In the HTML environment, it just prints out the topics in the master project and not the imported sub-projects.

[Peter Grainge]

Another career changer! While you were playing with tin cans, I was counting money, I spent thirty years in banking.

I'll give this some thought and post back. I'm guessing you are UK based. Whereabouts?

[Phil_Wells]

Close to London.

Have sent you e-mail via your website with more info.

[CraigCC]

30 years - took you that long to realise there's more money in robbing the banks than working for them 😉

[Peter Grainge]

Who said I wasn't robbing them? 🙂