Difference between revisions of "Integrate Custom Help Into MSDEV"
m |
m (Reverted edit of A, changed back to last version by Timarandras) |
||
Line 123: | Line 123: | ||
Also, try entering <code>ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm</code> in an (Internet )Explorer instance of your choice. This gives you a UI for the Help Collection Manager. Check whether your new collection appears there, and if it's enabled (checked). If not, enable it. If this fails, check whether your system has read access to the location where your help collection is stored. | Also, try entering <code>ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm</code> in an (Internet )Explorer instance of your choice. This gives you a UI for the Help Collection Manager. Check whether your new collection appears there, and if it's enabled (checked). If not, enable it. If this fails, check whether your system has read access to the location where your help collection is stored. | ||
− | + | ||
Sometimes, it happened to me that I needed to deactivate my newly registered collection, and activate it again, before it became accepted in MSDEV. De/Activation is done in the CollectionManager (URL see above), so you might want to try this, too. | Sometimes, it happened to me that I needed to deactivate my newly registered collection, and activate it again, before it became accepted in MSDEV. De/Activation is done in the CollectionManager (URL see above), so you might want to try this, too. | ||
Line 137: | Line 137: | ||
* [http://www.stack.nl/~dimitri/doxygen doxygen] | * [http://www.stack.nl/~dimitri/doxygen doxygen] | ||
* [http://www.antonypranata.com/articles/helpvc7.html Integrating Symbian Help in Visual Studio .NET] by Antony Pranata | * [http://www.antonypranata.com/articles/helpvc7.html Integrating Symbian Help in Visual Studio .NET] by Antony Pranata | ||
+ | |||
[[Category:Development]] | [[Category:Development]] |
Revision as of 20:48, 6 April 2006
Contents
- 1 Preface
- 2 Prerequisites
- 3 Creating the Compressed Help File
- 4 Converting the Help 1.x to a Help 2.0 project
- 5 Compiling the Help Title
- 6 Creating a new Help Collection
- 7 Registering the Help Collection & Help Title
- 8 Verify the Installation
- 9 Trouble Shooting
- 10 Precompiled UNOIDL reference help files for OpenOffice.org 2.0.2
- 11 References
Preface
This document describes how to integrate custom help content into the Microsoft Visual Studio (called MSDEV below) Help System.
The most interesting use case for this is to integrate OpenOffice.org source code documentation, or the OpenOffice.org IDL reference, into MSDEV.
Note that I did not investigate the matter to an end, I stopped when I saw the help collection in MSDEV, and successfully queries an identifier from the source code by pressing F1. So, I don't know whethere there are any pitfalls still waiting, and the document describes only what I found so far. However, results are quite promising ...
Prerequisites
General
- Microsoft Visual Studio .NET. Everything below is tested with the 2003-version
- Visual Studio .NET Help Integration Kit 2003 (free download)
Optional
If you plan to let doxygen generate your Compressed Help Files (.chm
), then you need
- HTML Help Workshop (free download)
- doxygen itself, of course
Creating the Compressed Help File
If your documentation is already exists in Microsoft Help 1.x format (that is, as a .chm
file), you can probably this step.
In your doxygen configuration file, ensure that
-
GENERATE_HTMLHELP
is set toYES
-
CHM_FILE
has a value ofsomename.chm
-
GENERATE_CHI
is set toYES
-
HHC_LOCATION
points to thehhc.exe
from the HTML Help Workshop, if it's not in your path (and also not in yourHKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths
registry branch).
Run doxygen with those options (and all other options as you prefer them). This should, amongst a heap of HTML files, create a .chm
file with a .chi
file besides.
Converting the Help 1.x to a Help 2.0 project
If you have a .chm
file, then this is a "Microsoft Help 1.x" format so far. For the next steps, you need a "Microsoft Help 2.0" project, which basically is a bunch of XML files with various extensions, describing the help content and structure.
For everything below, we'll assume that your files are named MyHelp.chm
and MyHelp.chi
Locate the hxconv.exe
from the "Visual Studio .NET Help Integration Kit 2003". Note that the installation routine of this kit did not only create a "VSHIK 2003" directory, but also (silently) a "Microsoft Help 2.0 SDK" (both usually in C:\Program Files
). You find hxconv.exe
in the latter directory.
Run
hxconv -o MyHelp MyHelp.chm
This will create a sub-folder MyHelp
, where MyHelp.chm
has been extracted, plus some additional files.
Compiling the Help Title
The next conversion step is to create some more *.Hx? files (the previous step already created some of them).
Locate hxcomp.exe
, also from the "Microsoft Help 2.0 SDK" directory. Change to the MyHelp
sub-folder created in the previous step, and run
hxcomp -p MyHelp.HxC -l logfile.txt
Here, -p MyHelp.HxC
specifies the help project file to compile, and -l logfile
simply specifies a file to log the processing.
Note that this step might take a while ...
Creating a new Help Collection
Create a new text file MyCollection.HxC
with the following content:
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE HelpCollection> <HelpCollection DTDVersion="1.0" FileVersion="1.0.0.0" LangId="1033" Title="My Help Collection Title"> <TOCDef File="MyCollection.HxT" /> <KeywordIndexDef File="MyCollection.HxK" /> <ItemMoniker Name="!DefaultToc" ProgId="HxDs.HxHierarchy" InitData="" /> <ItemMoniker Name="!DefaultFullTextSearch" ProgId="HxDs.HxFullTextSearch" InitData="" /> <ItemMoniker Name="!DefaultKeywordIndex" ProgId="HxDs.HxIndex" InitData="K" /> <ItemMoniker Name="!DefaultAssociativeIndex" ProgId="HxDs.HxIndex" InitData="A" /> <ItemMoniker Name="!DefaultContextWindowIndex" ProgId="HxDs.HxIndex" InitData="F" /> </HelpCollection>
Notes:
- Not sure what the
Title
attribute is good for here. Didn't find any place where it's visible.
This will be the root file of your new Help Collection. It refers to a table-of-content file MyCollection.HxT
, which you also have to newly create:
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE HelpTOC> <HelpTOC DTDVersion="1.0" PluginStyle="Hierarchical" PluginTitle="My Help Collection Title"> <HelpTOCNode NodeType="TOC" Url="MyHelpTitle"/> </HelpTOC>
Notes:
- the
PluginTitle
attribute specifies the title of the help collection in MSDEV, so make it human-readable and -understandable -
MyHelpTitle
can be chosen arbitrarily (it's not user-visible), and is referred to in a next step
Also, the MyCollection.HxC
above talks about a MyCollection.HxK
, so create it, too:
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE HelpIndex> <HelpIndex DTDVersion = "1.0" Name = "K" Title="K-Keyword Index" Visible="Yes" LangId="1033"> </HelpIndex>
Notes:
- not sure at all what this is good for ...
Registering the Help Collection & Help Title
Now, you need to register the previously created help collection.
Locate the hxreg.exe
, again from the "Microsoft Help 2.0 SDK" directory. Run
hxreg -n MyHelpNamespace -d "My Very Private Help Namespace" -c MyCollection.HxC
This creates a Help Collection namespace "MyHelp", with the detailed description "My Very Private Help Namespace", from the MyHelp.HxC
help collection.
Notes:
- the description (passed with the
-d
switch) is pretty irrelevant here. It's not visible to the user. - the namespace (passed with the
-n
switch) must be globally unique.org.openoffice
might be reasobale here if you're going to create OpenOffice.org-related documentation - the collection you specify here (the
-n
switch) is theMyCollection.HxC
you created in the previous step, not theMyHelp.HxC
. Don't confuse this.
Now, you have a new Help Collection, but not any content, yet. Run
hxreg -n MyHelpNamespace -i MyHelpTitle -s MyHelp.HxS -x MyHelp.HxI
Notes:
- the title ID (passed with the
-i
switch must be exactly the same as theURL
parameter of theHelpTOCNode
element in theHelpCollection.HxT
file. - If you don't have a
MyHelp.HxI
file, then you probably did not start with both a.chm
and a.chi
, but only with a.chm
which had intern index information. In this case, re-run doxygen with theGENERATE_CHI
option set toYES
, or de-compile and re-compile your.chm
file, and re-compile it with the after you added
[OPTIONS] Create CHI file=YES
to the respective Help 1.x Project File (.hhp
).
Thinking more about it ... it might be that you do not need the HxI file. Try just omitting the -x parameter, and report whether it works ...
Verify the Installation
To verify that the installation of your help collection was successfull, re-start MSDEV, and choose Help|Contents
from the menu. This should rebuild the help index (might take a while), and then show you your new help collection ...
You can now use the content from this collection in the usual way. In particular, you can place the cursor on an identifier in your source code, press F1, and jump directly to the respective help (if there is any) ... Pretty cool, isn't it?
Trouble Shooting
In case the new help didn't materialize in MSDEV: Try namespace.exe
from the Unsupported Tools
sub folder of the Help SDK. It gives you a graphical overview about registered help collections, so you can compare the data of your own (not-working) collection with the one for other collections - perhaps this gives you a clue.
Also, try entering ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm
in an (Internet )Explorer instance of your choice. This gives you a UI for the Help Collection Manager. Check whether your new collection appears there, and if it's enabled (checked). If not, enable it. If this fails, check whether your system has read access to the location where your help collection is stored.
Sometimes, it happened to me that I needed to deactivate my newly registered collection, and activate it again, before it became accepted in MSDEV. De/Activation is done in the CollectionManager (URL see above), so you might want to try this, too.
Precompiled UNOIDL reference help files for OpenOffice.org 2.0.2
A set of precompiled UNOIDL reference help files for OpenOffice.org 2.0.2 can be found in the file section on api.openoffice.org.
Simply download the file OpenOffice.org2.0.2_API_Reference_Manual.zip extract it anywhere and call the register.cmd. You will need hxreg.exe from the "Microsoft Help 2.0 SDK" to register the help files.