"Virtual" topics (chapters)

[MartienJ]

Dear All,

I am a happy H&M user for several years. One of our projects is growing out of control. It is used to describe a test rig which we build and from which we get an increasing number of versions. We use custom builds here and use both builds to topics and conditional text inside the topics where needed. In general we start making separate topics when the number of conditional statements inside a topic becomes overwhelming. However, when assigning a topic to a build process we get a linking problem. Suppose we have this:

Builds: VersionA and VersionB
Topic 1 describes a part which is quite different for version A and B , so we create two topics, 1A and 1B.
Topic 2 is general for both builds, which need to link to Topic 1.
Now we have some options
a) In topic 2 we create conditional text with for build VersionA includes a link to topic1A and for VersionB a link to topic1B.
b) We do not make two topics of topic 1 but keep a single topic which uses 'If VersionA then ... the full text op 1A end .. if Version B then the full text of 1B end.
c) We make a single topic 1 and create topic 1A and 1B outside the TOC and link them as snippets into topic 1 (which then still needs conditional text statements as described in b)

In this simple example any of the mentioned option works well, but we now have about 20 versions and a lot of different topics. I am wondering whether something like the following structure is possible:
a) I would like to create a "virtual" topic under the toc (Topic 1) which is further empty
b) I create two child topics (Topic 1A and Topic 1B), both with each own build (in fact a child topic needs to be created for each build, with possibly one default child)
c) Topic 2 should then only make a reference to Topic 1 and not to 1A or 1B (which is sufficient for us)
From an editing point of view this is ideal as in one glance I can see in the explorer which part belongs to which build.
However, when I do this I end up with a new chapter for Topic 1 with a single subchapter (e.g. Topic 1A) in e.g. a PDF output. So what is actually needed is that the "virtual" topic 1 does show itself in the TOC in the explorer of H&M but does not show up in the published TOC where only 1 of the childs is included.

Is something like this feasible or I am overlooking a better way to handle the case I described ?

Thanks in advance

Martien

[Tim Green]

Hi Martien,

I think that linked snippets will provide the solution you need here:

• Your Topic 1 is a TOC topic with its own TOC entry.
• Topics 1A, 1B and any other variants are created directly in the Project Files > Topic Files section (in their own folder, if you like) and do not have TOC entries.
• Topics 1A, 1B etc. have their build options set to "none" so they are never exported directly.
• Topics 1A, 1B etc. are inserted into topic 1 as linked snippets and surrounded by conditional text tags to include and exclude them as necessary.

Since the snippets are pasted into the topic where they are inserted at publish time they don't have their own IDs. The topic ID is always the ID of Topic 1, so you can always link to that. See this topic in the help for more information on snippets and how to manage them:

http://www.helpandmanual.com/help/index ... ippets.htm

Is that the kind of thing you were aiming for?

[MartienJ]

Dear Tim

Many thanks for your quick reply.

Using snippets is indeed according the third option (c) which I mentioned and this does indeed fulfill my requirements. Why I am less happy about this option is that:

a) We loose a direct overview in the TOC of which different Topics 1A, 1B etc exists (this overview is there if we use my option a and is quite handy)
b) Topic 1 becomes a little cluttered and quite long, if we need to set conditional text tags and have a longer list of topics 1A, B etc. Is there a way to set the linked topic to "not-visible" in order to show only the linked topic name? This would avoid errors in the "if then else end if" series.
c) Moving all Topics 1A, B etc into the Project files/topic section, does leave them "unstructured" as you don't see to which part they actually belong (e.g. if topic 1 is nested inside a few levels of chapters). I guess this can only be resolved by naming them appropriately ? You mention the use of different folders in the Project files/topic files section, is that a way to get some kind of "structure" into this topic list which can become quite long ?

Kindest regards

Martien

[Tim Green]

Hi Martien,

Is there a way to set the linked topic to "not-visible" in order to show only the linked topic name? This would avoid errors in the "if then else end if" series.

No, this isn't possible at the moment. However, we may add something like this in a future version.

Moving all Topics 1A, B etc into the Project files/topic section, does leave them "unstructured" as you don't see to which part they actually belong (e.g. if topic 1 is nested inside a few levels of chapters).

You can organize your snippets in folders and sub-folders in the Project Files section. This has no effect on the structure of your project. Alternatively, there is actually a more elegant solution to this: Instead of keeping them in the current project, create a snippet project for them. There, they CAN be in the TOC, so you can have an entire project of structured multi-topics (or even multiple projects) that you edit natively there. You just need to observe the following requirements:

• The snippet projects must be uncompressed HMXP projects. Then you insert the snippets with the From File option, selecting them in the /Topics folder of the source project.
• You need to include the /Topics folder(s) of your snippet project(s) in the Project Search Path of your project. This also means that snippet files with identical IDs are forbidden, because Help+Manual would always insert the first snippet with a matching filename that it finds.
• It's a good idea to use a style repository for your style if you do this, and link the repository to both your snippet project and your working project. Then you edit the styles for both projects in the same place in the repository. The repository can also contain snippet files, but it doesn't have a TOC so managing the files is actually easier in a separate project.