Oops

Hmm.. finally my layout engine for Inka is ready. Or so I thought. All tests are green, well, some are yellow, but come on. I was sure that I over-tested it and began planning to dramatically reduce the number of tests -- I start a demo app and discover that everything looks wrong!

Just can't help it!

Well, finally I'm at the point where I have to prepare an installer for Ivonna. Actually, I'm stuck at this point for about two weeks. Not because of installer itself, but because of the documentation. No, I diligently wrote all the xml comments, believe me. But these comments have to make way into a nice docs, preferably with some custom ("conceptual" in Sandcastle terms) content. And it has to be in Html Help 2.x format. This morning I finally discovered that my help can be viewed in the Document explorer. Was it because of the electricity been cut for a moment?

Anyway, here's my recipe. I'll be using VS 2005 with the 2007 SDK, Sandcastle January 2008 release, and DocProject 1.10.0 RC.

1. Install the VS SDK.
2. Install Sandcastle. It is important to install it after the SDK, because the SDK contains its own version of Sandcastle, which is too old. Anyway, if you installed Sandcastle first accidentally, just edit your DXROOT environment variable so that it points to the Sandcastle's folder.
   
3. Download and extract the presentation file patches. This fixes a bug in Sandcastle when you don't have a root topic.
   
4. Install DocProject. A major annoyance is a bug in the 1.10 RC version: the Add-in looks for the Project toolbar that has more than 40 items. Mine had only 38. The suggested workaround is to download the code and patch it manually, but I couldn't afford that, so, instead I wrote a macro that added 3 ugly entries to my Project menu. Anybody interested? Update: there's a 1.10.1 version that supposedly fixed this bug.
   
5. Add a DocProject to your solution. You can add a DocSite project instead if you need online help (it will build the offline help as well).
6. You might want to modify some templates offered by the DocProject wizard. But don't remove the feedback section entirely -- you'll get a JavaScript error later.
7. Modify the AssemblyInfo.cs file to reflect your documentation title and organization.
   
8. Don't ever rebuild the project -- it'll lose some essential files.
9. In the project wizard or later in the DocProject properties (available as an additional context menu item for your project), select "build html 2.0".
10. You might want to select the fastest build option -- choose "none" in the "build assembler options".
11. Now, after building the project, you have an HxS file in your output folder.
12. Unlike a chm file, you can't open it directly. Instead, you have to register it and navigate to it using the special ms-help protocol.
13. So, how do you register it?
14. The manual steps recommended copying a certain merge module from the sdk directory and manually editing it with Orca.
15. Like I was going to do that.
16. Actually I even did a first step.
17. But it turned out that there's a new kind of extensibility projects called "Help Integration Wizard". What you want is create a merge module that you'll add to your installation project. The wizard is pretty trivial, and it stores all its settings in the CollectionFiles folder, so you can edit them manually later.
18. At the first step, I chose the help file that I discovered in the Help/bin folder of my DocSite project.
    
19. The wizard showed me the structure of my future help. It contained one topic, called "sample topic" or something. it was on the left pane, and on the right there were my topics, conveniently excluded from the future help. I renamed the sample topic to "Ivonna", and added my topics under that root topic.
20. I also chose the namespace for my help -- ivonna.docs.
21. However, building the project didn't work for me, the postbuild event (the one that actually edited the merge module) failed. Invoking it manually from the command line failed as well. So, I opened the executable in the Reflector, and it turned out that it has been designed specifically in order to hide the possible cause of an error. For example, the exception was coming from a logging statement that was inside a catch block, so it was cleverly hiding the real exception. Also, all exception messages came from some native calls, so, for example, "File not found" turned into "Invalid handle".
    
22. So, I just wrote something that mimicked this app, and it somehow worked. Now I have a patched merge module that I can add to my installer. Update: It turned out that the problem was with the path -- it contained cyrillic characters. Once I created another project in a different location, everything went smooth.
23. Now, you should add the merge module from this project to your setup. You should probably create a Help folder under your app folder, and choose it for the merge module files. Choose the merge module in your setup project, and choose the folder in the Properties, KeyOutput -> MergeModuleProperties -> Module Retargetable Folder.
24. By the way, you can see all installed help namespaces via a handy utility located here: \Program Files\Visual Studio 2005 SDK\2007.02\VisualStudioIntegration\Archive\HelpIntegration\Unsupported\Namespace.exe
    
25. You probably want to include a shortcut to your documentation. It should be something like this: "%CommonProgramFiles%\Microsoft Shared\Help 8\dexplore.exe" /helpcol ms-help://ivonna.docs. Note that I put my namespace after the "ms-help://" stuff. Yes, you are even able to view it in IE.
    
26. After you successfully made the installer, you discover that when the documentation opens it shows an empty page. If you want an introduction or something to appear, you should register it as "DefaultPage". Details can be found here.
    
27. Modify your shortcut like this: "%CommonProgramFiles%\Microsoft Shared\Help 8\dexplore.exe" /helpcol ms-help://ivonna.docs /LaunchNamedUrlTopic DefaultPage.

By the way, you can download Ivonna from my new site here, and view the online docs (produced with DocProject) here. I'll be blogging about Ivonna on my site's blog.

Inka moved

Inka has finally changed its Unix name at SourceForge. You can find it at https://sourceforge.net/projects/inka.

Also, I'm finally building me a site, and there'll be a lot about Inka and how it should be used. Find it at http://sm-art.biz.