Snippets and multiple TOC references

<< Click to Display Table of Contents >>

Navigation:  Reference > Project Content >

Snippets and multiple TOC references

Help+Manual gives you two different ways to "reuse" topics in your project: The Snippets Tool, which inserts a copy of the contents of one topic or an external H+M XML file in another topic, and multiple references to a single topic in the Table of Contents (TOC). Both these methods have their advantages and disadvantages.

About multiple TOC references to a single topic:

Creating multiple TOC references to a single topic is a little like having several doors to the same room. You may be able to enter through different doors, but the room is always the same. A topic with multiple TOC references is still just one topic, but the user can display it by clicking on different entries in the TOC.

For the user it looks as though there is a separate copy of the topic in several different locations. Actually, however, there isn't. There is still just one topic, and this means that it is 100% identical in every location. It cannot have even the smallest difference because it is the same topic. The only difference that is possible is that you can have different captions (titles) for the TOC entries for each instance – the doors are different but the room is the same.

See Multiple TOC entries for one topic for instructions on using this feature.


The "multiple topics" do not increase the size of your output files because there is really only one topic.


All the "instances" have the same topic ID so it is only possible to create hyperlinks to the original instance.

For the same reason all keywords associated with the topic will always link to the original instance of the topic.

All the instances are 100% identical because they are the same topic. You cannot have different text before or after the "copies" in the individual locations.

About the Snippets Tool:

The Snippets Tool allows you to insert the contents of one topic in another topic. This can be done either in Copy mode or in Link mode.

Using Copy mode is like copying and pasting text. The contents of the other topic or XML file are pasted into the current topic and can be edited. Only the text is copied and once the copy has been made the text is part of the current topic. If the topic you inserted from is edited nothing changes in the current topic.

This mode is used for text blocks that you want to edit after inserting them, for example tables that need to be filled out.

When you use Link mode you create a link to the other topic or XML file. You can't edit the text inside the current topic but when the source topic or file is changed the changes are reflected in the linked copy as well. When you publish your project a static copy is made of the linked topic, but until then the link is dynamic and all changes in the linked topic are updated.

Linked snippets can be used in multiple places and all the "copies" will be updated simultaneously when the linked topic or file is edited. This mode is used for text that you want to use in many places in exactly the same way.

The current contents of the source topic are displayed in the editor at the insertion point with a shaded background.

In addition to this, the source topic or XML file also exports any index keywords it contains to the target topic. (With XML file snippets this only applies if the snippet is a full topic.) This means that any keywords associated with the source topic also only need to be entered once; they are automatically exported to all target topics and combined with any keywords the target topic already contains. This only works with index keywords, however. A-keywords, topic IDs and help context numbers are not exported, because this would cause logical problems.


This method has several important advantages over multiple TOC references:

You can include different text before and after the embedded topic. This makes embedded topics ideal for documentation where you need to repeat the same instructions in different contexts.

You can insert snippets inline, as formatted text that is part of an existing paragraph.

In the published output all the topics containing embedded topics are real, unique topics containing copies of the source information. Each topic has its own unique topic ID that can be linked to directly.

All normal index keywords are embedded together with the topic – you only need to enter the keywords for the embedded text once. (A-keywords are not embedded because this would cause logical contradictions.)


The only real disadvantage of embedded topics is that they make your project larger, but not really all that much larger. Text does not take up much room and multiple instances of  graphics don't inflate your file size because there is never more than one copy of identical graphics in your output file.

See Re-using content with snippets for instructions on using this feature.

See also:

Multiple TOC entries for one topic

Re-using content with snippets