In this post, I’ll show you how to create some simple content and add it to the Visual Studio local Help Library. The only tools you’ll need are a command prompt, Notepad, Windows Explorer and the Help Library Manager. This exercise takes about 5 minutes and, when you’re done, you can easily remove the content without any side effects to your help system. This tutorial makes the following assumptions:
- Visual Studio 2010 (RTM or SP1) is installed on your machine.
- You have administrator privileges on your machine.
- You have successfully used the local Help Viewer to read EN-US help content.
Step 1: Create a Topic
The basic unit of content in the help system is a “topicâ€. A topic is a single piece of XHTML content with a unique identity in the local Help Library.
To begin, create a folder for your help content and then create a topic in that folder. For the purposes of this tutorial, you’ll create a folder named “HelpTutorial†in your main Documents folder.
- Use Windows Explorer to create the folder or from a command prompt:
mkdir %userprofile%\Documents\HelpTutorial - Launch Notepad.
- Copy the following and paste it into Notepad:
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>My Custom Content</title>
<!-- Specify the topic content key: ID, locale and version -->
<meta name="Microsoft.Help.Id" content="b3382805-aa6b-4e6f-a346-73d20f74d0cd" />
<meta name="Microsoft.Help.Locale" content="en-us" />
<meta name="Microsoft.Help.TopicLocale" content="en-us" />
<meta name="Microsoft.Help.TopicVersion" content="10" />
<!-- Use the default branding package to render the topic -->
<meta name="Microsoft.Help.SelfBranded" content="false" />
<!-- Place the topic in the TOC under the root node -->
<meta name="Microsoft.Help.TocParent" content="-1" />
<meta name="Microsoft.Help.TocOrder" content="0" />
<!-- Enable topic access from the keyword index -->
<meta name="Microsoft.Help.Keywords" content="my custom content" />
<!-- Enable topic access via F1 help -->
<meta name="Microsoft.Help.F1" content="myTopic" />
<!-- Provide a description for use in the search results list -->
<meta name="Description" content="This text provides an overview of this topic and is displayed in the search results list." />
</head>
<body>
<h1 class="title">My Custom Content</h1>
<div id="mainSection">
<p>This is an example of a simple, well-formed library topic.</p>
</div>
</body>
</html>
- Save the file as: %userprofile%\Documents\HelpTutorial\topic1.html
- Close Notepad.
Interlude: Anatomy of a Topic
In this segment, we’ll look more closely at the topic you just created. If you want to load your topic into the local Help Library as quickly as possible, skip to Step 2: Create a Package to continue on with the tutorial.
First and foremost, our topic needs to be a well-formed XHTML Basic 1.1 topic that can be consumed by the .NET Framework XmlReader class. All tags must be properly closed and you must use the correct HTML encoding for symbols and special characters.
Our text-only content is located between the <body> tags. We want the same look-and-feel as the Visual Studio documentation so we’re using the standard “branding packageâ€. This branding package will format our topic correctly if it includes the following markup:
- Add
class="title"in the topic heading tag - Place the body text inside a
<div>withid="mainSection"
<body> |
Now let’s look at the metadata in our topic. The purpose of this metadata is to enable discovery and navigation of help system content. The metadata is specified using standard <meta> tags located in the <head> section of the topic.
The <title> tag determines how the topic is displayed in the Table of Contents (TOC). Note that, while the system enables the topic title to be different than the topic’s H1 heading, it is customary for them to be identical.
<title>My Custom Content</title> |
In the help system, a topic’s identity (called the “content keyâ€) consists of the topic ID, topic version and topic locale. The content key enables the same topic to exist in multiple documentation versions and multiple human languages. It is important for the Microsoft.Help.Id meta tag value to be unique within the help system. While this can be set to any string value, it is customary to use a GUID to ensure uniqueness across content from multiple vendors. The Microsoft.Help.Locale meta tag tells the indexer which word breaker to use when parsing the topic for search terms. If this tag is omitted, the help system defaults to the word breaker associated with the Windows operating system locale setting. The Microsoft.Help.TopicLocale meta tag enables the system to distinguish between different locale versions of the same topic, for example, when both English (EN-US) and Japanese (JA-JP) content are both present in the local Help Library. Finally, we set the topic version to content="10" since this is Version 1.0 of our topic.
<!-- Specify the topic content key: ID, locale and version --> |
The look-and-feel of the topic (font, color, spacing, behaviors, etc.) is specified by our branding package. Creating a custom branding package is outside the scope of this tutorial so we’ll just use the standard branding package that ships with Visual Studio. Note that the standard branding package is used by default so this tag is optional and is included here for completeness.
<!-- Use the default branding package to render the topic --> |
Normally, we’d set the value of the Microsoft.Help.TocParent meta tag to the Microsoft.Help.Id of another topic. This establishes our position in the TOC hierarchy. In this case, we want the topic to appear as a child of the TOC root node and to do that we set content="-1". The Microsoft.Help.TocOrder tag tells the system how to order our topic relative to its peers. Children of the root node sort by TocOrder first, then by topic ID. All other nodes in the TOC sort by TocOrder first, then by title, then by topic ID.
<!-- Place the topic in the TOC under the root node --> |
We want the topic to be discoverable from the keyword index and we’ll use the Microsoft.Help.Keywords tag to do this. Multiple index entries can be specified by repeating this tag. For best results, keyword index strings should be highly related to this specific topic.
<!-- Enable topic access from the keyword index --> |
We also want this topic to be accessible from F1 Help inside the Visual Studio IDE. We’ll use the Microsoft.Help.F1 to assign our F1 Help string. The F1 string must be highly related to this specific topic to enable an unambiguous F1 help query.
<!-- Enable topic access via F1 help --> |
Finally, we specify a user-friendly description of this topic. The topic description is displayed, along with the topic title, in the search results pane.
<!-- Provide a description for use in the search results list --> |
In Help Viewer 1.x, all of the help system artifacts (table of contents, search index, keyword index, etc.) are generated from topic metadata. Because of this, it is important that topics are well-formed and contain appropriate meta tags to behave well inside the help system. The Help Viewer 1.0 SDK provides a more complete treatment of help system meta tags.
Step 2: Create a Package
Now that you have a topic, it’s time to place that topic in a “packageâ€. A package is a collection of topics and their associated resources (images, scripts, etc.). Packages are ZIP files with an .MSHC extension.
The help system was designed to scale to extremely large libraries. Some of the Visual Studio content sets have almost 200,000 topics. Packages are used to break up these content sets into smaller chunks that are used to transport content from an online endpoint to the end-user’s hard drive. By convention, packages include no more than 10,000 topics.
Placing your topic in a package is simple:
- In Windows Explorer, right click on the topic1.html file we created in Step 1 and send it to a Compressed (zipped) folder named mycontent.zip.
- Rename the mycontent.zip folder to mycontent.mshc. (Click ‘Yes’ on the Rename dialog that pops up.)
Step 3: Create a Book
The last step in preparing your content is placing your package in a “bookâ€. A book is a collection of packages and is defined in an asset manifest file named HelpContentSetup.msha.
Content is added to or removed from the local Help Library one book at a time. Even if you only want to add a single package to the local Help Library you must place it in a book. If packages are the unit of transport, you can think of books as the unit of install.
In this tutorial, you’ll use the following settings:
| Vendor: | My Company | |
| Product: | My Custom Content | |
| Locale: | EN-US | |
| Book Name: | My Custom Topics |
You supply the help system with information on how to display your new book in the Help Library Manager by creating an asset manifest (.MSHA) file.
- Launch Notepad.
- Copy the following XHTML content and paste it into Notepad:
<html xmlns="http://www.w3.org/1999/xhtml">
<head />
<body class="vendor-book">
<div class="details">
<span class="vendor">My Company</span>
<span class="locale">en-us</span>
<span class="product">My Custom Content</span>
<span class="name">My Custom Topics</span>
</div>
<div class="package-list">
<div class="package">
<span class="name">mycontent</span>
<span class="deployed">true</span>
<a class="current-link" href="mycontent.mshc">mycontent.mshc</a>
</div>
</div>
</body>
</html>
- Save the file as:
%userprofile%\Documents\HelpTutorial\HelpContentSetup.msha
(Tip: Set the “Save as type†dropdown list in Notepad to “All Files (*.*)†) - Close Notepad.
Step 4: Install the Book
You should now have the two files that make up your book in the HelpTutorial directory: mycontent.mshc and HelpContentSetup.msha.
In Version 1.x of the Microsoft Help Viewer, local help content is added, updated and removed from the Visual Studio 2010 local Help Library with the Help Library Manager (HLM). HLM can be launched with command line parameters that will help you get the job done.
- Launch a command prompt with administrator privileges. Administrator privileges are required when a book is not wrapped in a digitally signed CAB file. (More on that later.)
- From the prompt, change to the location of the HLM utility:
cd %programfiles%\microsoft help viewer\v1.0 - From the prompt, instruct Help Library Manager to add your book to the Visual Studio help catalog:
- Click on the ‘Add’ link. (Note that the size is an estimate of the book size and is rounded up to the nearest megabyte.)
- Click on the ‘Update’ button.
- At this point, the system requests permission to proceed because the book is not wrapped in a digitally signed CAB file. Click on the ‘Yes’ button.
- The help content in this tutorial was not pre-indexed so the system automatically creates the necessary search indexes. Wait for the index merge to complete.
- Click on the ‘Finish’ button.
You’re done! Note that the only tools you needed were a command prompt, Notepad, Windows Explorer and Help Library Manager. And every component of your work could be inspected with either Notepad or a web browser.
Step 5: Explore Your New Content
Take your new content for a test drive. Launch Visual Studio 2010 and select “Manage Help Settings†from the Help menu. In Help Library Manager, select “Choose online or local help†and verify that your preferred help experience is set to “I want to use local help.â€
Now “Check for updates online†and confirm that the new book appears in your content list.
Cancel out of HLM and select “View Help†from the Visual Studio Help menu. Note that your topic appears in the Table of Contents as a child of the root node just as you specified in the Microsoft.Help.TocParent meta tag.
Switch to the Index tab and enter “my custom content†in the index search box. You specified this index item in the Microsoft.Help.Keywords meta tag. Clicking on the index item takes you to your topic.
Type Ctrl + E to go to the Help Viewer search box and enter “My Custom Contentâ€. While the exact position of the topic in the result list will vary depending on the content you’ve installed, you should see it on the first page of search results.
Close the Help Viewer and open a code editor in Visual Studio. Type “myTopicâ€, highlight “myTopic†and press the ‘F1’ key. Help Viewer should open to your newly installed topic. You specified the topic’s F1 value in the Microsoft.Help.F1 meta tag.
How do I remove the book from my Help Library?
Launch HLM and select “Remove Contentâ€. Click on the Remove link corresponding to My Custom Topics.
Can I distribute my book to other people?
Yes. However, if you want to eliminate the security alert dialog during install and make your content accessible to non-administrators, you’ll need to place your book in a signed .CAB file.
How do I create MSDN-style content?
OK, you’ve successfully added a topic to your local Help Library but that topic isn’t very interesting. If you want to add links and MSDN-style controls (code examples, collapsible areas and language-specific text) to your content, check out my post on adding links and code examples to help topics you create.
To learn more about creating and branding content for Microsoft Help Viewer 1.x, check out these resources:
- The Help Viewer 1.0 SDK goes into greater detail on how to create, brand and deploy content.
- For more complex projects, I highly recommend using a help authoring tool.
- The Help Guy blog is a good resource for anyone creating Help Viewer content.
- Microsoft Help MVP Rob Chandler has assembled a nice overview of Microsoft Help Viewer 1.0.
5 Comments