XML Help

Lotech Solutions (www.lotechsolutions.com)

Unfortunately, there is no simple method to integrate an XML Help solution into the VS.NET IDE. You need to create a separate Microsoft Installation file (MSI) which consists of numerous manually created and interrelated XML files, then hack that installation file using the Windows Installer SDK Orca program. 

This topic expects that you have already created an XML Help project and compiled it into an XML Help solution.

To integrate an XML Help solution into VS.NET

1. In VS.NET, open the XML Help project solution. 
2. Create a separate install (MSI) project. Show more ...

To create a separate Help install project

1. Add a new project to the XML Help solution.

 

3. Create the collection level XML Help files.
4. Update the product install file (as located or created in step 2 above).
5. Rebuild the product install file for distribution.

We've also got to install \\Syd-file2\Technology\Tools\NUnit V2.0.1\Nunit.msi to build locally and run unit tests.

To download and install Windows Installer SDK

1. In Internet Explorer, navigate to http://www.microsoft.com/msdownload/platformsdk/sdkupdate/

If prompted, accept the 'Microsoft Web Installer' ActiveX license agreement. 

2. In the left pane, click on the Windows Installer SDK link.
3. On the 'Windows Installer SDK' download page, click the Install this SDK link.

The 'Confirm Install Selections' page displays.

4. Click the Continue button.

The 'Platform SDK Installation Wizard — Web Page Dialog' displays containing the license terms. 

5. Click the Accept button.

The installation location request page displays. 



Click the Continue button.

6. The 'Installation Status' page displays. Click the Install Now button. 

The dialog displays the download and installation progression.



7. When finished, click the Close button.

The 'SDK Update Catalog' page displays, checks your locally installed components, and displays the result.

8. Click the Show installed SDKs button.

You should see that "Windows Installer SDK" is in the list, and marked with Installed.

9. Exit IE, then shutdown and restart your computer.

The Windows Installer SDK adds new Windows Start menu items under Start | Programs | Microsoft Platform SDK August 2002. Select Platform SDK Documentation to view the online help for the product.

To install Orca

This procedure expects that you have already downloaded and installed the Windows Installer SDK.

1. Using Windows Explorer, navigate to 'C:\Program Files\Microsoft SDK\Bin\'.
2. Right-click on Orca.msi and select Install from the popup menu.

The Orca Installation Wizard will display.

3. Follow the prompts and select the Complete option.

The Orca.exe program is accessed through the Windows Start menu under Start | Programs | Orca and is also added to the right-click context sensitive menu item Edit with Orca in Windows Explorer.

To use Orca to edit collection install and merge files

This procedure expects that you have already installed Orca.

1. Using Windows Explorer, navigate to your XML Help collection installation program (<XMLHelpCol>.msi) usually located in the Release folder for your XML Help project. For example: "C:\Ci Documentation\CitectObjectServer\TestXMLHelp\HelpDemo\Release\HelpDemo.msi".
2. Right-click and select Edit with Orca from the popup menu.

The Orca installation database table editor program will display.



Scroll down the left side to view the list of installation database tables in the open MSI file. You could click in any cell displayed in the right pane to edit the contents (should you wish to do so).

3. In the (left pane) Tables list, select the File table.
4. In the (right pane) FileName column, click and highlight the row containing the XML help project HXC file name.
5. In the File column, select the contents of the cell (of the highlighted row) then click the clipboard Copy button (as highlighted by the red square in the screenshot above).

This copies the contents of the cell to the clipboard for later use.

6. From the Orca main menu, select File | Open, then navigate to and select the merge file named "MSHelp2_RegTables__RTL_—-_—-.msm" from the _setup folder of your XML Help collection. This is the file you manually copied in to the project earlier.

   

7. In the (left pane) Tables list, select the HelpNameSpace table.
8. In the (right pane) double-click in any cell to bring up the 'Add Row' dialog.



There are four fields for this table, each consisting of a name-value pair. Select each field in-turn from the list, and enter its respective value in the textbox within the frame labelled "Column". (Intuitive isn't it?) The following table lists the value for each field required to get your XML help collection integrated properly into VS.NET:

Column	Data
NamespaceKey	<CorporateID>.<HelpProductName>.<LanguageID>
NamespaceName	<CorporateID>.<HelpProductName>.<LanguageID>
File_Collection	<CollectionIDNumber>
Description Help	<DescriptiveText>

Where:

<CorporateID> = Required placeholder for a unique ID for the Corporation supplying the collection being merged

<HelpProductName> = Required placeholder for the name of the collection being merged

<LanguageID> = Required placeholder for the number of the language of the collection

<CollectionIDNumber> =  Required placeholder for the number copied from the project MSI file in the earlier step

<DescriptiveText> = Optional placeholder for a descriptive text string about collection being merged

9. Enter appropriate values into each cell and click OK. See the screengrab from step 6 for examples.

The File_Collection field uses the number you copied from the project MSI file in an earlier step of this procedure. Simply click the Paste button.

To do something else

Pre-requisites go here

1. Step 1
2. Step 2

More blurb goes here

Wrap up conclusion goes here

See Also

Lotech Solutions' Tips, Tricks, and Procedures | What is XML Help | How to navigate around the VS dotNET IDE

 email webmaster

Copyright Lotech Solutions. All rights reserved.