Authoring Help Files for WPF with Word 2007-2010

• Download setup - 928.62 KB
• Download source - 529.36 KB

Introduction

This article introduces an application that will allow developers to display a help document and integrate it into their applications.

Background

The idea below this tool is that in the Windows 95 - XP era, there was a uniform way of providing help content for applications: WinHelp and HtmlHelp along with some web based solutions. But the development of HtmlHelp in this form has been discontinued and the newer versions are only available for displaying help inside Visual Studio. The objective was then to provide a standalone help viewer that could be easily extended and integrated with WPF based applications.

Sora HelpSystem provides an extensible base to display help content for any WPF based applications with the possibility to generate help content from different sources. At the moment, the help content can be created manually or imported from a Microsoft Word 2007-2010 document using a tool based on Word To XAML.

In the future, the help content could be generated directly from a collection of Word Document and Assembly XML Documentation.

Sora HelpSystem

Sora HelpSystem is a collection of different OpenSource tools hosted at CodePlex. They are licensed under LGPL meaning that you can freely use those tools even in a commercial application. Note that this license apply to the HelpView, the HelpEdit and the base library. WordToXaml has his own license that should be followed, thus conditioning the redistribution of XamlImport.

HelpView

Residing in HelpView.exe, this is the viewer application used to display the help files. To directly open a help file, simply run HelpView.exe with the help file passed as an argument of the process.

HelpEdit

This application allows some basic edit operation for the help file. The preferred way is to generate the help content from a Word document.

Base Library

Consisting of Sora.Data.dll, Sora.FileSystem.dll and Sora.HelpSystem.dll, this is the runtime of the Help provider required to run the Viewer, the Editor, or your application if you embed some help containers in it.

Generating the Help Content from a Word Document

The main advantage of this technique is that you can use your preferred content editor to write your help files. When you have your content, you will be able to generate a help file straight from your document and finalize it with the help editor.

Note that only docx documents can be imported (Word 2007 and Word 2010). Also, you must have Microsoft Word installed...

The only thing that you must be aware of is that you have to define some markers for the page that you are writing. Before starting the content of a help page, you must include the following text:

[DSHELPSECTION:] relative/page/uri | page title

The page content...  

The relative page URI is the URI without the starting ds-help://help.document/. Also, there are some special pages:

• start: This is the first page shown when the help file is opened. In this page, you may present briefly your help document and introduce the subject.
• header: This is the static text shown at the top of any page using the HelpViewer.
• error404: This is the page shown when an URI was not found in the document.
• errorException: This page is shown when an error occurs in the viewer. Hopefully this page should never be visible...

You can also define a link in your document pointing to other pages. When displayed in a document, a link will be resolved when clicked. You can create (using Microsoft Word) a link to a webpage (by using a standard link such as http://www.google.com) and a help page (by specifying the relative page URI as the link target).

Once your content is written, you can import it using the XamlImport tool. In the setup, it is located in the installation directory of Sora HelpSystem (a shortcut is present in the start menu). The XamlImport syntax is the following:

XamlImport [-m] source_file [target_file]

The -m switches indicate that if the target_file already exists, the generated file will be merged with the target_file. This allows to chain the generation of a help file from several sources.

The source file can be either a Word Document (DocX), or an XAML file containing a FlowDocument (such as the output generated by the tool WordToXaml Converter).

If the target_file is not specified, the name will be built changing the extension of the source file to .dshelp.

The resulting file will be openable in the HelpViewer. If there are some inconsistencies or details that you want to correct in the resulting help file, you can use the HelpEdit application to edit your help document.

Embedding Help Content in a WPF Window

One common task of a developer is to provide some help content directly in an application. Such content includes ToolTips or description for a specific control. Usually you have to write such texts in your XAML (or use a magical way to retrieve it from some external tools).

The idea here is to load this content directly from the help file. The first step is to have the references to the Help Provider. You will have to add references to those 4 assemblies:

• Sora.Data.dll (Database Engine)
• Sora.FileSystem.dll (Storage Engine)
• Sora.HelpSystem.dll (Help Engine)
• Sora.HelpSystem.UI.WPF (WPF UI Tools)

Once you have added those references, you have to define the HelpSource of your current document. You can have several sources but each component will be linked to a unique source. Thus, you can change on the fly the selected help document for your entire window by changing the help source (allowing scenarios such as providing a localized help file, depending on the current culture of the application).

<Window x:Class="SampleWPFApplication.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:help_ui="clr-namespace:Sora.HelpSystem.UI.WPF;
		assembly=Sora.HelpSystem.UI.WPF"
        Title="MainWindow" Height="450" Width="525">
    <Window.Resources>
        <!-- This object will provide the help document. 
		The source is relative to the current directory.
        If not found, the source is relative to the directory of the main assembly -->
        <help_ui:HelpDocumentSource x:Key="WindowHelp" Source="SampleHelp.dshelp"/>
    </Window.Resources>
 ... 
</Window> 

Then, you can provide content using two ways:

Displaying a Complete Page from the Help Document

 <!-- This control can show help content from a document.
The document is linked to a HelpDocumentSource and the Uri is defined in CurrentPageUri -->
<help_ui:HelpContentDisplay Name="helpContent" 
Document="{Binding Source={StaticResource WindowHelp}, Path=Document}"
CurrentPageUri="ds-help://help.document/items/information" Height="100"/> 

The HelpContentDisplay is the host for help pages. You can display a page by providing a source (the property Document, which is linked to the help source of the window) and a URI (the address of the page, displayed when browsing the page in the HelpViewer).

Note that you can also specify a page as a search result by using the URI ds-help://help.document/search?words+to+search. The control will then display a page with the search result, and the user will be able to navigate to a result by clicking on a hyperlink.

Also, you can specify a web page by providing an URI like http://www.google.com.

Loading Plain Text from the Help Document

Another way is to provide some text directly from the help document as a source for a property like the Text property of a TextBlock. You can achieve by using the following syntax:

<TextBlock Text="{help_ui:HelpText DocumentSource={StaticResource WindowHelp},
   PageUri=ds-help://help.document/items}"/>

The content is provided by a Binding Extension allowing you to feed your help content to any property accepting a string value.

Note that only text will be shown. No image or link will be displayed.

Going Further

In the future, it will be possible to generate the help content from more sources. The next step should be generating the content from the XML comments of an assembly as with a tool like Sandcastle.

Generating help content from a source is basically writing a FlowDocument: this is the format used internally by the runtime to store the content. The XamlImport tool is a good example of such process (the obscure part being processing the generating document for the markers).

Don't hesitate to look at the project sources on CodePlex. If you have any questions or comments, you can also post them at the CodePlex page of the project or here.

History

• 10/12/2010: Initial version