Migtating two Robohelp X5 HPJ projects using shared files

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
T-Kern - Writer
Posts: 4
Joined: Sat Nov 16, 2019 1:12 am

Migtating two Robohelp X5 HPJ projects using shared files

Unread post by T-Kern - Writer »

I have been a Robohelp-for-Office user "forever" but decided to make some real effort in 2019 to see if it was worth the time and effort to move to a more modern HAT. I presently endure the mental pain of using Robohelp X5 from 2005. It suffices for creating our .chm help file but things could be better or easier.

After doing my due diligence on current HATs I settled mainly on H&M but also trying it out against Robohelp 2019 (due to the expcted easier project migration from X5). However, Robohelp 2019 Classic isn't much better than Robohelp X5. Robohelp 2019 non-Classic, and its new UI, is a step back in time to Neanderthal days.

I have spent quite a bit of time with H&M but decided to post this question because I am no super expert at this time.

My current situation:

1) The main CHM project is generated from a HPJ file with all the primary .doc and .rtf files.

2) I have a second CHM project which shares 80% of the files from project #1 and replaces, locally, 20% of those same-named .doc and .rtf files via the HPJ file. The idea is to create two "similar" CHM files but with unique, localized content and two different TOCs.

I find this system very easy to use and maintain since I can just edit the two .hpj project files to determine which .doc files are shared between them and which ones are made local to project # 2. Both, naturally, have their own TOC file, but share the exact same topic links amongst the two set of files.

My question: how can I replicate this setup in H&M? If I blindly import the two .hpj files, as two H&M projects, then I will end up (naturally) with two set of completely unique files. On the flip side, I will need to import each .hpj file to set up the files + links properly. With Robohelp I could easily manage this situation simply via the HPJ files and which RTF files they reference.
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Migtating two Robohelp X5 HPJ projects using shared file

Unread post by Tim Green »

Hi "T-Kern" and welcome to the forum! A first name would be nice so that people can address you... :)

This situation sound perfect for Help+Manual's multiple TOC feature:

https://www.helpandmanual.com/help/hm_w ... multi.html

You then have all your topics in the same project and the main TOC would be the one that uses the majority of the topics. Then you create a secondary TOC for the second output. Secondary TOCs function like conditional build options: They only export the topic files that actually have entries in their TOC. Everything else is filtered out automatically unless you explicitly include it with build options or link to it.

What you would do is import the first HPJ project to a new Help+Manual project. Then, with that project open, import the second HPJ project into the first one using the Import option in the File menu. The open question is whether the existing links would get resolved when you do that. If you have problems with it, please write to us at support AT ec-software.com (replace the AT with @) and we may be able to find a solution.

Note that multiple TOCs is only one way to manage this. There are at least two others:

1) Modular projects
You create a master project and as many separate project modules as you need for the TOC blocks that you want to combine. The modules are then referenced in the TOC in the positions you want to insert them and published (compiled) together as if they were a single project. Modules can be included and excluded with conditional build tags and remain completely independent.

https://www.helpandmanual.com/help/hm_a ... dular.html

2) Share topics in a style repository
If you need more flexibility in the reusable topics you can store them in a style repository, which can also be used as a central stylesheet for multiple projects. You would import everything you need from your HPJs to a normal Help+Manual project, then save that as a style repository. Then you create separate projects for your two outputs and insert the shared topics from the repository as snippets. The shared topics would only be edited in the repository. This has the added benefit that snippets are inserted into existing topics: You can have more than one snippet in a topic and insert custom content between the snippets.

https://www.helpandmanual.com/help/hm_a ... ories.html
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
T-Kern - Writer
Posts: 4
Joined: Sat Nov 16, 2019 1:12 am

Re: Migtating two Robohelp X5 HPJ projects using shared file

Unread post by T-Kern - Writer »

Thank you for all of these suggestions. I have just finished up two very intense days of trying to learn H&M and to force-fit + merge my two help systems into one H&M project. There was a lot of roadblocks to overcome but I was able to achieve a working prototype.

One hard learnt lesson was that I needed to create two new children TOCs before I imported my two RoboHelp project files so that I could have proper conditional output of those two merged help projects. I also learned that I needed to be careful with the names of the merged source files + ensure that there was no link collisions.

After all of this work I did have some key feedback:

- There is no warning of file or link collisions from H&M. For example, if I import files from two directories with the same .rtf filename (and identical topic names in the two files) then H&M offers no warning nor output error that a directory name or link name collision has occurred. I could only discern this problem after the fact and with no guarantee that I discovered all possible collisions.

- I'd ideally like to have the "Topic Options" panel be made to be optionally floating just as with the Keywords window. I spend too much time clicking back and forth between the Editor and Topic Options tabs.

- I find that the hyperlinks in the Reports do not work. I am aware with Windows 10 that Drag&Drop no longer works (either in Admin mode or non-Admin mode, one of those two) - I'm not sure if that is a related issue.

- As requested by at least one other person on the forum, H&M would really benefit from a "Dead links" dedicated dialog box. Just as they had rightfully noted, the Report HTML page is far too long and overly complicated. It's so very easy to do in RoboHelp X5 as I only have to tab over to the Broken Links tab then click through the short list. I stumbled across a screen snapshot of another HAT program which has a multi-tabbed dialog box that shows things like broken links.

- From my short experience of the last two days I did feel that H&M was lacking in one key area. Since I have two projects merged to one, there is no "Preset" functionality in the Publish page. Right now, when I go to Publish, I have to select amongst: (1) The TOC to use, (2) the skin to use and (3) the output filename. As I would be flipping between my sub-projects often, and for decades to come, I would not want to change these settings almost every time I published a CHM file.

- As reported in my other forum post + email, the import of the RTF files from Word 2000 does have a lot of issues, of which they may boil down to some common fixes.

I hope some of these suggestions may come in useful in the near or long term.
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Migtating two Robohelp X5 HPJ projects using shared file

Unread post by Tim Green »

Hi T-Kern,
- There is no warning of file or link collisions from H&M. For example, if I import files from two directories with the same .rtf filename (and identical topic names in the two files) then H&M offers no warning nor output error that a directory name or link name collision has occurred. I could only discern this problem after the fact and with no guarantee that I discovered all possible collisions.
Please provide some details on what you did here. Help+Manual will not permit the creation of duplicate topic IDs in the the same project. However, if you are importing to multiple modules, which are completely separate projects, then there are no collisions until you try to publish them to a single output. This can be avoided by using a different ID prefix in each project:

https://www.helpandmanual.com/help/hm_a ... r_ids.html
- I'd ideally like to have the "Topic Options" panel be made to be optionally floating just as with the Keywords window.
Click on the gear icon in the top left corner of the topic editor and choose "Show editor and topic options side by side".
- From my short experience of the last two days I did feel that H&M was lacking in one key area. Since I have two projects merged to one, there is no "Preset" functionality in the Publish page.
That is what the Publishing Task Manager is for. You get all your requests there and much more besides. Check out this chapter in the help:

https://www.helpandmanual.com/help/hm_w ... tasks.html
- As reported in my other forum post + email, the import of the RTF files from Word 2000 does have a lot of issues, of which they may boil down to some common fixes.
As explained in our mail correspondence, at least some of these issues appear to derive from the fact that RoboHelp rewrote the RTF files, so they are not, or not entirely, Word RTF. Re-saving them as RTF in Word is a solution for a lot of these issues.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
T-Kern - Writer
Posts: 4
Joined: Sat Nov 16, 2019 1:12 am

Re: Migtating two Robohelp X5 HPJ projects using shared file

Unread post by T-Kern - Writer »

Hello Tim

Please excuse my short delay in responding. I had it in mind to get this information back to yourself.
Please provide some details on what you did here. Help+Manual will not permit the creation of duplicate topic IDs in the the same project. However, if you are importing to multiple modules, which are completely separate projects, then there are no collisions until you try to publish them to a single output. This can be avoided by using a different ID prefix in each project
Let's take a very simple example. I have two RoboHelp projects A.hpj and B.hpj both with a main.rtf primary file. Each of those files have a '#main' topic. Each also have their own TOC for which their first entry points to #main. Since my goal is to merge these two projects into one H&M project, I "import" A.hpj then follow up by an import of B.hpj. Naturally there is going to be a problem with the merging process since I have two RTF files with different topics yet the same #references of "#import". After importing the two TOCs both will point to the same topic and not to their unique topics. I do understand why this may be happening. However, at the very least, I'd like some stats output to the warnings panel after import stating that there was some topic name collisions during import - using that information I could go back to the source files and make all topic IDs unique. Right now there are no warnings.
That is what the Publishing Task Manager is for. You get all your requests there and much more besides. c
You are so correct.
I had completely missed the "New task" button and had somehow felt that there was only a set number of tasks to choose from. A new user issue. My mistake.
Click on the gear icon in the top left corner of the topic editor and choose "Show editor and topic options side by side".
Yes, but that doesn't work well for my monitor layout. I have a 1280x1024 19" monitor for which the TOC, editor + topic options panel are too crowded when side by side. What I wish to do is have the topic options panel float, as does a few of your other panels, so that I can put it elsewhere on my 3 monitor setup.
User avatar
Tim Green
Site Admin
Posts: 23155
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Migtating two Robohelp X5 HPJ projects using shared file

Unread post by Tim Green »

Hi T-Kern,

It would be very helpful if you could zip up two small demo HPJ projects that cause this kind of conflict and mail them to me at support AT ec-software.com (replace the AT with @) so that we can look into this. :)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Post Reply