Choosing TOC entries that will be included

[Jure Erznoznik]

I have to deal with large help projects that need to be split into multiple files. What's more, some of those files are then used in multiple projects, but not in their entirety: some of the TOC entries are used in each project. The entries used overlap and that's the primary reason why I chose to use a common file describing all those topics so that I don't have to write the same stuff each time I want to display it.
I have considered splitting these files by 1st level TOC, but then I would have zillions of tiny files that would be hard to maintain.

Question/suggestion: Would it be possible to include a feature which would allow me to tell H&M which (1st level) TOC entries to include into the merged TOC? That would also mean that (in case of compile-time merging) only those topics, their keywords, their linked topics, etc. would be merged into resulting .chm, .pdf, etc.

[Tim Green]

Jure: I'm not quite sure that I've understood exactly what end result you're trying to achieve but I think it's already possible by using a combination of a modular help system and planned use of the "Builds which include this topic" options in each topic.

When you use "Builds which include this topic" for 1st-level topics their child topics are automatically included unless you actively turn them off. Also, any linked topics are always included, even if they are not included in "Builds which include this topic", because otherwise the project and the help file would be broken. (The only way to change this is by removing the links to the topics you don't want to include.)

If this is what you mean see Modular Help Systems in the H&M help for more details. If not, please describe what end result you're aiming at in a little more detail...

[Jure Erznoznik]

You didn't understand correctly what I meant. Builds are not what I need in this case.

I will try to give you a better example:
Look at H&M "Modular help systems" introductory page. You will see an example of a modular help file with two modules (Module_A, Module_B). Suppose you don't have 2, but 2000 modules that are usually dealt with in one single topic, rarely does this topic have children to describe a module in more detail. You also have 20 projects, project1 using Module_A, Module_B, Module_C and Module_D, project2 using Module_A, Module_D, Module_G, etc.

What I would actually like to do is:
- Merge Module_A, Module_B, etc into one single file for easier maintenance
- Include only the needed modules into master project file so that the user does not have to browse through zillions of descriptions that are never seen in his particular application.

This would all have been easy if I left Module_A, Module_B, etc. in separate files, but then I would have too many of these files. It is practically not acceptable for me to have this sort of arangement.

[Tim Green]

I see what you mean now. Yes, at the moment the only way to manage different versions is to keep them as separate files, because as soon as they are physically merged into a project you no longer have a common source.

I think the feature you would need would be a master file that would also allow direct editing of the separate source files and displaying the TOC structure of the child modules within the master file, in addition to specifying which versions should be included in the build -- then you could maintain a common source and still be able to manage the project quite efficiently.

I am sure that Alex will comment on this, however, I suspect that it would require a radical restructuring of the way that H&M works.

By the way: What did you mean by

2000 modules that are usually dealt with in one single topic

??? I'm afraid I don't understand it. Do you mean that each module would be a different version of one topic, with or without child topics?

[Jure Erznoznik]

What you described would actually be an advanced version of what I had in mind, but it is totally correct. The only thing that is not really needed is direct editing of source files, I just need the TOC (a flag on it that would say "Include me into this master project")

Those "2000 modules that are..." means that they are simple descriptions of some simple procedures like maintenance of inventory items, warehouses, tax rates, etc. They do not represent the same topic, but simple topics.

[John Smith]

Maybe I am misunderstanding your problem, but maybe a simple architecture change, coupled with turning builds on or off would be a solution.

It seems that in your introductory topics for each Help Project or other parent topics, you describe the child topics or other topics in detail, and thats where the problem occurs. Why not use more generic text, that does NOT specifically describe another topic or link to it. If you definitely require more detail, make that a topic that can be turned off or on. You may also be able to use conditional text.

For Example

Welcome
---Description for Version 1
---Description for Version 2
---Description for Version 3

or

Welcome
---Description for all Versions (generic)
---New Features for Vers2
---New Features for Vers3
---module Vers 1
---module Vers 2
---module Vers 3
---module All Vers
------Child for Vers 1
------Child for Vers 2
------Child for Vers 3

or

Welcome
---Topic (generic) with Conditional Text, and/or embedding of hidden topics, for Vers1, or Vers 2 or Vers 3

Then you just turn on or off (Builds) the topics/modules you want, in each help project as you combine it into a master project. A parent topic would not be confusing as it would not discuss child topics that didn't exist.

I had a similar problem where my parent topic used to give a brief description of each child topic, but it meant that I could not simply add a new child topic, or delete one. I always had to change the parent topic.
Now I have a very brief explanation or no text at all, and I made the Topic Heading (which appears in the TOC) more descriptive.

With so many topics that need to be turned off or on, you may want to consider Autoit, which can automatically turn off the builds based on the project you want. For example it could open a Help project, turn off or on the builds for either Topics or Modules, then open another Help Project (Module to the first one) and turn off or on the builds within the module, etc, etc.