You can insert topics and XML files into your current topic at the cursor position. These topics can be inserted in Copy mode or Link mode. In Link mode the snippet content updates automatically when the source topic or XML file is edited.

The topics can be in your current project, another Help+Manual project or a directory of H+M XML files.

Procedure

1.Click in your topic where you want to insert the snippet.

2.Select the Insert Snippet tool in Write > Insert Object.

3.Choose From Topic to insert a topic from the current project or From File to insert an external H+M XML file or a topic from another project.

4.Select the topic or file you want to insert and click on OK to insert it.

Options:

•Copy & Paste inserts a copy of the file contents that you can then edit.

•Linked creates a live link to the file – changes in the source file or topic are updated automatically.

•Snippet begins a new paragraph inserts the snippet as a new paragraph. Turn this off to insert the snippet text inline inside an existing paragraph. If the snippet contains paragraphs they will also be inserted, of course!

•Use project search path to locate snippet adds the location of the snippet file to the project search path. If you deselect it the absolute path to the snippet is stored with the snippet.

A style repository is a special kind of Help+Manual project that is used to share styles and snippets between multiple projects. Before using a style repository you need to create it from a Help+Manual project and link it to your current project. See Working with Style Repositories for instructions.

To insert snippets from a style repository just select the From Repository option in the Insert Snippet dialog and then select the topic ID of the snippet you want to insert. All the other options are the same as inserting snippets from topic files in the current project.

The advantage of a style repository is that its styles are also merged with those of your project, so that the styles used for the snippets in the style repository project are also available for use in the project where you are inserting the snippet.

You can export selected text or the current topic to an external XML file, for example for use as a snippet in a snippet directory.

Export the entire topic:

1.Select the topic you want to export in the Project Explorer (TOC or Topic Files).

2.Select File > Save Topic to File in Project > Manage Topics and choose the save location.

Export selected text:

1.Select text in the editor – the text can include anything that a topic can contain, i.e. also images, tables, etc.

2.Select File > Save Snippet in Project > Manage Topics and choose a save location and a filename.

If you save in the uncompressed XML format you can also copy the XML files directly from your project directory to other locations in Windows Explorer (Professional and Floating license versions only).

You can insert snippets from any location. However, if you use snippets from many locations your linked snippets will not be displayed if you move your project or send it to someone by email. You can solve this problem by storing your snippet files together with your project in a special directory.

1.Create a folder for your snippets in a location where you can easily transport it together with your project folder.

2.Add the path to the snippets folder to your Project Search Path in your project's Configuration > Common Properties settings.

3.When you insert a snippet select the Use project search path to locate snippet option to tell Help+Manual to look for the snippet files in the folders listed in the Project Search Path.

When you do this you can always move your snippets folders to any location you like. To get Help+Manual to find the snippets you just need to add the new location to your project search path.

By far the easiest way to manage snippets is in a 'snippet project', which is just a normal Help+Manual project saved in uncompressed XML (.hmxp) mode. You then insert your snippets by selecting the XML topic files from the /Topics sub-folder of this snippet project. Help+Manual topic files can be used as snippets without restrictions.

Add your styles to the snippet project!

After creating your snippet project it's a good idea to add the paragraph and text styles used in your snippets to the snippet project. You should do this before adding any snippets to the snippet project – if you add them later the styles may not be used properly.

1.Select Styles > Edit Styles in the Write tab.

2.Select Copy Styles From... and then select your main Help+Manual project (i.e. the project in which you are going to use the snippets). This will replace all the styles in the snippet project with those from your main project.

Adding new snippets to a snippet project

•Just create a new topic or topic file in the snippet project, just as you would in any other Help+Manual project.

Adding existing snippets to a snippet project

•Move the XML snippet files to the /Topics folder of your snippets project in Windows Explorer.

Saving snippets to a snippet project from another project

•Create the snippet as you would normally and save it in the /Topics folder of your snippets project.

When you do this you can always move your snippets folders to any location you like. To get Help+Manual to find the snippets you just need to add the new location to your project search path.

You can also manage snippets in special Help+Manual projects called "style repositories". When a style repository is linked to your project all the snippets it contains are automatically displayed for selection in the Insert Snippet dialog.

•In addition to direct access to the snippets, the advantage of a style repository over a normal snippet project is that its styles are merged into the styles of your current project. The snippets using the styles defined in the repository are thus automatically formatted correctly because their styles are directly available.

•The disadvantage of a style repository is that you can only link one repository with any project. However, you can also use both a linked style repository and additional manually-created snippet projects (see above).

See Working with Style Repositories for full details on how to create style repositories and register and link them to your projects.

When you use topic files from your current project as snippets you will generally want to exclude the source files from your published output. If you don't do this these files will be published and the user will able to find them with Search in formats like HTML Help and WebHelp.

1.Select the entry of the topic file in the Project Files section of the Project Explorer.

2.In Project > Manage Topics select Change > Include in Builds and deselect all build options. This will ensure that these topics will never be included when you publish your project.

This is not necessary for snippets inserted from other projects or external XML files, of course!

There are three ways to edit the content of external snippet files in Help+Manual. Which you use depends on whether the snippet contains a small or large amount of text. However, by far the easiest way to manage and edit snippets is to organize them in a 'snippet project' of their own, for which Help+Manual Professional is required (see further above on this page for more details). In addition to this, you can also manage snippets in a style repository project.

Locating and editing the source files of linked snippets directly

Just right-click on the linked snippet in the Help+Manual editor and select Locate Snippet Source, or hold down CTRL and click on the snippet.

Create a snippet project (Professional and Floating license versions only):

See the instructions further above on this page for more details on this.

•Create a new Help+Manual project and save it in an empty folder in uncompressed XML (HMXP) mode. Note that this save option is only available in the Professional and Floating license versions of Help+Manual.

•Create new snippet files by creating new topics in the snippet project, or create the snippets in another project and save them to the /Topics folder of the snippets project.

•Add existing snippet files to the 'snippet project' by moving their XML files to the /Topics sub-folder in the snippet project folder. The topics will then appear in the Topic Files section of the snippet project. You can create TOC entries for them for easier organization by dragging the topic files into the snippet project TOC from the Topic Files section.

Create a style repository project (Professional and Floating license versions only):

In addition to "normal" snippet projects you can also manage snippets in a "style repository", which is a special kind of Help+Manual project for managing reusable topics and styles. See Working with Style Repositories for full details on this.

Editing small snippets stored as individual files:

1.Press ENTER a couple of times to create some space in the current topic.

2.Insert the snippet file you want to edit in Copy & Paste mode (see above) and make the necessary changes.

3.Select the edited text and export it as a snippet, overwriting the original snippet file (see above).

Editing larger snippets stored as individual files:

1.Create an empty dummy topic in the TOC.

2.Select File > Load Topic from File in Project > Manage Topics and load the snippet file.

3.Edit the content and then select File > Save Topic to File and overwrite the original snippet file.

If a linked snippet contains an anchor (jump target) you can link to it from other topics. However, since the snippet file is not really inserted in the current topic you cannot select the anchor from the drop-down list next to the Target: field in the Insert Hyperlink dialog. You need to enter the anchor name manually.

1.Make a note of the name of the anchor you want to link to.

2.Create a normal hyperlink to the topic containing the linked snippet.

3.Double-click on the hyperlink to edit it and type in the name of the anchor in the drop-down list box next to the Target: field.

4.Publish your project and test the link to make sure that it works.

You won't have this problem with snippets inserted in Copy mode because the text containing the anchor is inserted in the topic directly.

You can use the Find Referrers function to check where a topic file is being used as a linked snippet. You can also use the same function to find the location of the linked snippet topic files inserted in the current topic.

This only works for topic files used as snippets in the current project. It won't work across multiple projects or for XML files that are not part of projects.

1.In the Project Explorer select the topic file – either a file containing a linked snippet or a file that you think is being used as a linked snippet.

2.Select Find > Find Referrers in Project > Manage Topics (or just right-click and select Find Referrers).

3.The sources of linked snippets in the topic are shown as incoming links. Topics in which the topic is used as a linked snippet are shown as outgoing links.

If snippet files are H+M topic files containing index keywords the keywords are imported when you use Link mode. A-keywords are not supported in snippets, however.

Keywords are not imported with snippets in Copy & Paste mode. Small snippets saved from selected text do not include keywords – that is only possible when you save an entire topic as a snippet.