| |
  |
This article provides a walkthrough of all the steps required to create a .HELP file, and display it on a computer with Microsoft Windows [Version 6.0.4051] codename "Longhorn" installed. If you have installed this release, the required .NET framework 1.2.3070 is installed at the same time, too.
Note: Alpha version 4074 is released in the meantime. Information is still subject to very strong changes at the moment.
© 2003 Microsoft Corporation. All rights reserved.
Microsoft, are either registered trademarks or trademarks of Microsoft Corporation
in the United States and/or other countries.
You can get a graphic user interface "Longhorn Help compiler GUI" with that one the compiling and decompiling of a *.HELP file is more easily (now: xHelpMarkup).
In a first step we want to look at the required files in a diagram (© Microsoft) and a table.
| Extension | Purpose | HTML Help Equivalent |
| .help | Help file | .chm |
| .packinglist | Packing List (All project files) | .hhp |
| .taskimp | Task Implementation file | - |
| .helpmd | Help Metadata file | - |
| .xml | Topic files | .htm |
| HelpCompiler.exe | Help Compiler | hhc.exe |
The files used in the authoring process are shown in the table. The compiling process is very similar to earlier Help file creation processes. An essential difference to HTMLHelp (CHM) consists in the fact, that the produced help file (*.help) is compiled but isn't compressed.
The first order of business is creating the Help topics to display. This content is authored using Microsoft Assistance Markup Language (MAML). Great changes lie ahead in the technical documentation of programs. Rob Chandler (www.helpwaregroup.com) mentions it: "Tech Writers Need to change" in his paper "UI & UA Changes on the road to Longhorn". His paper looks at what is happening in the User Interface (UI) and User Assistance (UA) design while traveling the road to Longhorn. Contains essential information for all designers.
To create Help topics
before starting see note: Alternative
possibility for compiling
1. Create a directory to store your project files.
2. Launch the XML or text editor of your choice.
3. Create a new blank document and paste in the following content:
<?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>
<para>This demo is edited by Help Information (c) Ulrich Kulle</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& version=6.0.0.1&bundleid=LonghornHelpDemo&topic=/Topic2.xml">Topic 2</link>. </para>
</content>
</section>
</sections>
</conceptual>
4. Save the document as Topic1.xml in the folder you created in step 1.
5. Repeat steps 2 and 3, using the following content, and saving as Topic2.xml:
<?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 2</title>
<content>
<para>This is the second topic of the "Longhorn" Help authoring demo.</para>
</content>
<sections>
<section>
<title>Link demonstration</title>
<content>
<para>Here is a link back to <link xlink:href="help://microsoft.windows/default.aspx
?language=en-us&version=6.0.0.1&bundleid=LonghornHelpDemo&topic=/Topic1.xml">
Topic 1</link>.</para>
</content>
</section>
</sections>
</conceptual>
There are two project files required to create a .HELP file: the packing list file, and the metadata file. The packing list (.packinglist) file is a list of all files to be included in a .HELP file. It is the only file that is passed to the compiler. The Help metadata (.helpmd) file defines the virtual file structure and URIs for a .HELP file, and identifies which files should be picked up by the Promotion Manager at run time.
Because each Help topic must be associated with a task, two additional files are required: the task implementation file, and the task definition file. These serve to define a new task category called "Help System", and to associate the introductory topic with its task.
NOTE: The file formats for task declaration will be completely redesigned in the next release (6.0.4074). The markup provided in this walkthrough is solely intended to provide the desired functionality for the demonstration.
Create a new document and paste the following content:
<?xml version="1.0" encoding="utf-8"?> <packingList copyright="Microsoft Corporation 2003" langId="1033" fileVersion="1.0.0.0"> <entry url="LonghornHelpDemo.helpmd" /> <entry url="LonghornHelpDemo.taskimp" /> <entry url="LonghornHelpDemo.taskdef" /> <entry url="Topic1.xml" /> <entry url="Topic2.xml" /> </packingList>
Save the file as LonghornHelpDemo.packinglist in your project folder.
To create the Help metadata file:
1. Launch the XML or text editor of your choice.
2. Create a new document and paste the following content:
<helpMetadata xmlns="urn:schema.setup.microsoft.windows.com">
<helpFileIdentity name="LonghornHelpDemo" publicKeyToken="1111222233334444" version="1.0.0.0">
</helpFileIdentity>
<description>
<product name="microsoft.windows" serverUrl="www.help.microsoft.com" version="6.0.0.1">
<bundle name="LonghornHelpDemo" language="en-us" description="Longhorn Help Authoring Demo">
</bundle>
</product>
</description>
<topics>
<topic title="Longhorn Help Demo: Topic 1" subUrl="/Topic1.xml" url="help://microsoft.windows/
default.aspx?language=en-us&version=6.0.0.1&bundleid=LonghornHelpDemo&topic=/Topic1.xml">
</topic>
<topic title="Longhorn Help Demo: Topic 2" subUrl="/Topic2.xml" url="help://microsoft.windows/
default.aspx?language=en-us&version=6.0.0.1&bundleid=LonghornHelpDemo&topic=/Topic2.xml">
</topic>
</topics>
</helpMetadata>
3. Save the file as LonghornHelpDemo.helpmd in your project folder.
Create the task implementation (.taskimp) file
1. Launch the XML or text editor of your choice.
2. Create a new document and paste the following content:
<?xml version="1.0" encoding="utf-8"?>
<assembly xsi:schemaLocation="urn:schema.setup.microsoft.windows.com Component.0.0.0.5.xsd"
manifestVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:schema.setup.microsoft.windows.com">
<assemblyIdentity name="LonghornHelpDemo" publicKeyToken="1111222233334444" version="1.0.0.0" />
<description>
<DisplayName>Longhorn Help Demo</DisplayName>
<OwnerType>Windows</OwnerType>
</description>
<memberships>
<categoryMembership name="Microsoft.Windows.Shell.Tasks"
publicKeyToken="5555666677778888" version="1.0.0.0">
<task name="Longhorn_Help_Demo.0001">
<entryPoint name="LHD_entrypoint.0001" />
</task>
</categoryMembership>
</memberships>
<entryPoints>
<taskProviderEntryPoint name="LHD_entrypoint.0001"
clsid="C69A61FF-9CEA-42C3-9651-D2B014A84CE9"
data="help://microsoft.windows/default.aspx?language=en-us&version=6.0.0.1
&bundleid=LonghornHelpDemo&topic=/Topic1.xml">
</taskProviderEntryPoint>
</entryPoints>
</assembly>
3. Save the file as LonghornHelpDemo.taskimp in your project folder.
Create the task definition (.taskdef) file
1. Launch the XML or text editor of your choice.
2. Create a new document and paste the following content:
<?xml version="1.0" encoding="UTF-16"?> <assembly manifestVersion="1.0" xmlns="urn:schema.setup.microsoft.windows.com"> <assemblyIdentity name="LonghornHelpDemo" publicKeyToken="1111222233334444" version="1.0.0.0"> </assemblyIdentity> <description> <DisplayName>Longhorn Help Demo</DisplayName> <OwnerType>Windows</OwnerType> </description> <memberships> <!--Task Declarations--> <categoryMembership name="Microsoft.Windows.Shell.Tasks" publicKeyToken="5555666677778888" version="1.0.0.0"> <task name="Longhorn_Help_Demo.0001" UID="635106e5-d089-4b6b-b2c5-52d11b2b89f5" displayName="Longhorn Help Demo (task)" displayNameSingleSelect="" displayNameFolderSelect="" displayNameMultiSelect="" toolTip="" icon="" isPinnable="False" isAppSpecific="False"> </task> </categoryMembership> <categoryMembership subcategory="Microsoft.Windows.Shell" name="Microsoft.Help.Collection" publicKeyToken="5555666677778888" version="1.0.0.0"> <CollectionMember taskName="Longhorn_Help_Demo.0001">
</CollectionMember> </categoryMembership> <categoryDefinition name="Microsoft.Windows.Shell.CatalogCategory" version="1.0.0.0" publicKeyToken="5555666677778888" subcategory="97c98cb3-9333-42a5-8601-242d518834af"> <CatalogCategory displayName="Help System"> </CatalogCategory> </categoryDefinition>
<categoryMembership name="Microsoft.Windows.Shell.CatalogCategory" version="1.0.0.0" subcategory="97c98cb3-9333-42a5-8601-242d518834af" publicKeyToken="5555666677778888"> <CategoryMember taskName="Longhorn_Help_Demo.0001"> </CategoryMember> </categoryMembership> <!--Assign SubjectTerms to the Tasks--> <categoryMembership name="Microsoft.Windows.Shell.SubjectTerm" version="1.0.0.0" publicKeyToken="5555666677778888" subcategory="Help System" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SubjectTermMember taskName="Longhorn_Help_Demo.0001" /> </categoryMembership> </memberships>
3. Save the file as LonghornHelpDemo.taskdef in your project folder. IMPORTANT: the .taskdef file must be saved with Unicode encoding.
Now you're ready to compile the .HELP file. Note that the compiler (HelpCompiler.exe), which is included with this whitepaper, is only compatible with the Windows "Longhorn" operating system for this release Build 4051.
To compile the .HELP file
1 . Open the command window.
2. Navigate to the local directory that Helpcompiler.exe is located in.
3. At the command prompt, use the following syntax to run the compiler, substituting
the path to the packing list file with the path to the file in your own project:
helpcompiler -p c:\myProject\LonghornHelpDemo.packinglist
4. When processing is complete, a file named LonghornHelpDemo.help will be added to your project folder.
You can get a graphic user interface "Longhorn Help compiler GUI" with that one the compiling and decompiling of a *.HELP file is more easily (now: xHelpMarkup).
Use the Help Installation and Indexing Tool to install your .HELP file into the Windows file system.
To run the Help Installation and Indexing Tool
1. Copy LonghornHelpDemo.help to C:\Windows\Help.
2. Right-click the status bar and select Task Manager.
3. Open the command prompt (DOS window) in addition.
4. Navigate to C:\Windows\System32.
5. Type "nuimpmpx" (without the quotes), then press Enter.
6. Check Task Manager to verify that the process nuimpmpx has
finished (it will no longer appear in the Task Manager window).
The registration process initially finds and registers all *.help files on the system. It can take time to do this, needs many resources and the process runs on a pentium 4 with 512 MB RAM and 1.8 GHz for some minutes.
You can use the following procedure to view the installation log file at any time.
To view the Promotion Manager log
1. Open the command prompt.
2. Type "cd %temp%" (without the quotes), then press Enter.
3. Type "cd HelpTraceLogs" (without the quotes), then press Enter.
4. Type "notepad promotionmanager.txt", then press Enter.
To launch the Help Pane and view the Longhorn Help Demo
1. Click Start, then Run, type "helppane" (without the quotes), and
press Enter.
2. At the top of the Help Pane, click Options and select View all Tasks.
3. In the list of tasks, scroll down to the category named "Help System",
and double-click "Longhorn Help Demo" to display the introductory
topic. You can also perform a search for "Longhorn Help Demo".
 |