Creating Custom Topics

Introduction

This tutorial provides instructions on how to add custom HTML topics to Help 1.x output (.chm). The content of a raw HTML topic is entirely up to you. You can use any valid HTML file as a topic in compiled help.

MAML Recommendation

DocProject 1.10.0 RC provides first-class support for authoring conceptual documentation using the XML-based Microsoft Assistance Markup Language (MAML). It is highly recommended that you use MAML instead of following this tutorial.

Sandcastle builds MAML documentation into HTML topics that have the look and feel of the chosen presentation style, in much the same way that your XML documentation comments are transformed into HTML topics automatically. If you write conceptual documentation using MAML you'll be able to import all of your topics into new DocProjects and DocSites at a later time to take advantage of updates to Sandcastle presentation styles. You could even switch the presentation style by creating a new DocProject or DocSite, then copy in the Help\Settings\topics.xml file, which defines the TOC, and import your MAML topics using the Import button in Topic Explorer.

See How To Use The Topic Management Dialog for more information.

Requirements

To follow this tutorial you must have the HTML Help Workshop (Help 1.x) compiler installed on your computer, as well as DocProject and Sandcastle.

For more information, see the Latest Release Notes.

Preparation

If you have decided not to use MAML instead (see above), then follow these steps to set up a new or existing DocProject or DocSite so that you may add custom HTML topics.
  1. Create or open an existing DocProject or DocSite.
    1. Make sure that your DocProject produces Help 1.x output. For more information, see How To Configure DocProject.
  2. If you haven't built the project yet since the last time that it was opened, build it now. For more information, see How To Build Compiled Help With DocProject.
The purpose of building now is to get a full build out of the way (if the build is skipped that's fine too) so that the next can be a partial build, but we must only work with certain files in the project otherwise we may cause a full build again. A full build will automatically replace our changes to the Help 1.x project files and regenerate all files in the Help\Html folder.

For more information on full and partial builds, see Build Process.

Create a custom topic

  1. Locate your project's Help folder in Solution Explorer.
  2. Create a new subfolder and name it, Custom Topics.
  3. Add a new HTML file and name it, My Custom Topic.htm.
  4. Open My Custom Topic.htm in Design mode.
  5. In the Properties window, change the document's Title. For this tutorial you can use, My Custom Topic as the value.
  6. Write the topic. The HTML and format is completely up to you.
    1. Important: Mimicking the look and feel of a Sandcastle presentation style is not recommended. Use MAML instead (see above) to author help topics that look and feel like the chosen Sandcastle presentation style.
  7. Save the changes when you are done.
Linking to other custom topics
You can link to other custom topics by file name. For example, the following HTML will link to a custom topic named, My Second Topic: <a href="My Second Topic.htm">My Second Topic</a>

Linking to auto-generated reference topics
You can also link to auto-generated reference topics by file name. For example, if you've configured your project to use friendly HTML file names then you can use the following HTML to link to the methods overload page of a class named, MyClass: <a href="T_MyClass_Methods.htm">MyClass Methods</a>

If you're not using friendly HTML file names then your link must specify the GUID file name of the topic. GUID file names do not change with each build since they are not actually GUIDs, they are MD5 hashes of the topic's ID formatted as GUIDs.

Include your custom topic in compiled help 1.x

  1. In Solution Explorer, copy each individual file in your Custom Topics folder into the Html folder, which should already contain all of the HTML topics that were generated by Sandcastle when you built the project previously.
    1. You can hold Ctrl while left-clicking files to select more than one, or Shift to select a range, and then while holding the Ctrl key again, drag and drop the selected files into the Html folder.
  2. Note: Each time you perform a full build the Html folder will be replaced. See below for instructions on how to automate this step.
  3. For more information on partial build items and full builds see, Build Process.

Include your custom topic in compiled help 1.x, automatically

  1. Open the BuildProcess.cs or BuildProcess.vb file, depending upon the language of your DocProject. For this tutorial we'll work with C#.
  2. Locate the BeforeExecuteStep method override and update it so that it looks like the following code snippet:
public override bool BeforeExecuteStep(IBuildStep step, BuildContext context)
{
  stepStart = DateTime.Now;

  if (string.Equals(step.Name, "Compile Help 1.x", StringComparison.OrdinalIgnoreCase))
  {
    TraceLine();
    TraceLine("Importing custom topics...");
			
    int count = 0;
    string rootFolder = context.TargetDirectory;
    string sourceFolder = System.IO.Path.Combine(rootFolder, "Custom Topics");
    string targetFolder = System.IO.Path.Combine(rootFolder, "Html");

    foreach (string topicFile in System.IO.Directory.GetFiles(
      sourceFolder, "*.htm", System.IO.SearchOption.AllDirectories))
    {
        System.IO.File.Copy(topicFile, 
          System.IO.Path.Combine(targetFolder, System.IO.Path.GetFileName(topicFile)), 
          true);  // overwrite

      count++;
    }

    TraceLine("{0} topic(s) imported.", count);
  }

  return true;
}

The code above will automatically copy all files with an .htm extension that are found in the Custom Topics folder, including all subfolders, recursively, into the Html folder.

For a sample that automates the process even further by automatically merging custom topics into the TOC, see the following blog post by Ben Hall:

http://blog.benhall.me.uk/2007/07/sandcastle-docproject-and-creating.html

Include your topic in the Html Help Workshop TOC

  1. Locate the Html Help Workshop table of contents (TOC) file in Solution Explorer.
    1. It will be in the root of the Help folder, but you may need to Show all files to see it.
    2. It has an .hhc extension and an icon that looks like an open book.
  2. Double-click the file and it will open in Visual Studio's HTML editor.
    1. Note: The contents of this file is HTML, not valid XML. Do not format this document or else it may be corrupt and will no longer work as expected.
  3. Locate the place in the TOC where you want your topic to appear, and then insert it.
    1. The workshop TOC format isn't so easy to understand. You should examine other topics to see how they have been included and just copy one to use as a template for your new entry. Don't forget to update the template with the name and location of your new topic though.
  4. Save your changes.
Important: The next full build will replace this document and you will lose your changes. You can either keep a copy of the document somewhere else in your project and then merge the changes manually after each full build, or you can allow the changes to be discarded and add them again manually. The best choice, however, is to use Ben Hall's solution and automate the process.

You may also want to add an entry for your topic to the index file, .hhk, but note that the format of the document is different than the TOC file.

Build

Build your DocProject or DocSite again and your topic will be included in the Help 1.x output.

If a full build occurs, or if DocProject doesn't detect any changes to the project's build items and skips the build entirely, then you can delete the .chm file to force a partial build the next time that the project is built.

Last edited Apr 4, 2008 at 2:50 PM by davedev, version 8

Comments

No comments yet.