Ryan Dawson on Longhorn

The software we think, but do not write

April 2004 - Posts

  • System.Help

    Filed under:

    System.Help

     

    So, they have been hard at work creating a task-oriented help system that is extensible and easy to understand.  I guess it now time that we stop using our own system and partake in the fruits provided.

     

    Some clarifications from above should probably be in order:

     

    • Task-oriented – The new help system has a new intermediate data format that maintains the intent of the help file.  By placing the content within task-oriented XML tags the Help runtime can determine the display using its own XSLT.  So, let me say that again.  The help file writer does not concern him/herself with the presentation.  Among the many benefits of a system like this are that it is easy to author and it maintains a consistent look across programs.

     

    • It is extensible.  Each help file is contained within an XML file.  That means that a typical project would contain n XML files, where n represents the number of help topics provided by the author.  Also, some book-keeping files: a .helpmd (which is a list of all the topics, .taskdef (a CLR mapping file), .taskimp (extension to .taskdef), and a .packinglist (which is analogous to the MSBUILD file, it contains all the files which are going to be compiled).  These are all compiled into a .help file.  Lastly, the help topics use XLink to link between each other.  XLink is not a totally revolutionary idea, but I would say this is the first application in which I have seen it used –which is revolutionary.

     

    • It is easy.  Take it at face value that I was able to get a help system up and running in 20 minutes.

     

    • Lastly, as implied by the title of this article, the help system is supported by a programmatic interface in .NET.  Among other things, this allows me to control the help pane by switching between different help topics with different UI interactions.

     

     

    In case you are wondering what the help pane looks like, here goes:

     

     

     

    For the image above, here is the content for the topic:

     

    <?xml version="1.0" encoding="UTF-8"?>

    <conceptual xmlns="http://schemas.microsoft.com/maml/2003/5" xmlns:doc="http://schemas.microsoft.com/maml/internal" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schemas.microsoft.com/maml/2003/5

    C:\Program Files\Microsoft Longhorn SDK\misc\MAML_Schema\Maml.xsd" xmlns:xlink="http://www.w3.org/1999/xlink">

      <title> Longhorn Help Demo: Topic 1</title>

      <content>

        <para> This is the introductory topic of the "Longhorn" Help authoring demo.</para>

      </content>

      <sections>

        <section>

          <title>Link demonstration</title>

          <content>

            <para>Here is a link to <link xlink:href="help://microsoft.windows/default.aspx?language=en-us&amp;version=6.0.0.1&amp;bundleid=LonghornHelpDemo&amp;topic=/Topic2.xml">Topic 2</link>.</para>

          </content>

        </section>

      </sections>

    </conceptual>

     

     

    I would like to note that the above code is straight from an easy to follow sample on getting the help system running.  The overview can be found here: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwmscintroducingwindowslonghornhelp.asp, while the actual download is here: http://download.microsoft.com/download/6/c/5/6c58007f-d204-4281-a14d-8c53d9bbc198/Longhorn_Help_Authoring_Walkthrough.EXE.  The download contains the helpcompiler.exe and the sample: Longhorn_Help_Authoring_PDC.mht

     

     

    When you get the help file built and installed, you can begin to reference it in code:

     

    string uri = @"help://microsoft.windows/default.aspx?language=en-us&version=6.0.0.1&bundleid=LonghornHelpDemo&topic=/Topic1.xml";

    System.Help.Pane pane = new System.Help.Pane();

    pane.DisplayTopicFromUri(uri);

     

     

    Note that there are 3 assemblies to choose from; for this specific example, you are going to want the System.Help.Pane assembly.  This code will start up the help pane and give you the image at the top of this article.

     

    PostTypeIcon
    5,080 Views