Blog‎ > ‎

Help News post MVP Summit

posted Feb 25, 2010, 6:32 PM by Robert Chandler   [ updated Mar 4, 2010, 9:20 PM ]
Last week I was lucky enough to spend 3 days with help team (along with the other Help MVPs) at the MVP Summit at Microsoft Seattle.
Here's some things I picked up.

Hide the Embedded Topic Navigation Pane

You will notice that most offline topic pages have an embedded search + loBand style navigation pane. 
In the RC build you can now hide this pane in offline help by appended the parameter "&embedded=true".

So this URL will show the navigation

  • http://127.0.0.1:47873 /help/1/ms.help?method=f1&query=system.string&product=vs&productversion=100&locale=en-us
    http://127.0.0.1:47873 /help/1/ms.help?method=f1&query=system.string&product=vs&productversion=100&locale=en-us&embedded=false

This URL wont show the navigation

  • http://127.0.0.1:47873 /help/1/ms.help?method=f1&query=system.string&product=vs&productversion=100&locale=en-us&embedded=true

Yes &embedded=true does the hiding and &embedded=false does the showing. The intent of the parameter was specifically for 3rd party viewers and the notion of whether the complete UI was embedded in another app vs. just being displayed in the browser. If embedded in another app, the assumption was that the app would (possibly) be responsible for providing their own TOC implementation. So embedded wasn’t referring to the nav, but the complete rendered/branded content.

RC Bug  - F1 wont work in Online mode with alternative viewer

I just reported a minor bug where F1 wont work in Online mode if you specify an alternative viewer (via registry setting HelpViewerProgID).

When you have F1 + Online + Alternative Viewer hooked up, Agent incorrectly appends "&embedded=true" parameter to the online URL causing a 404 type error.

I've added a work around to H3Viewer and Logged the problem at connect.

REST - Representational State Transfer

Help Integrators would have noticed some interesting new file formats introduced by MS Help Viewer.
The .msha Manifest file looks like XHTML. And API calls are send as URLs.

There is a name for this programming style.. its name is REST.
REST uses readable XML or XHTML files. You can read more about REST here...

LCID= instead of Locale=

The F1 and Page API calls can now use either lcid= or locale=
eg. ms-xhelp:///?method=f1&query=system.string&product=vs&productversion=100&locale=en-us
eg. ms-xhelp:///?method=f1&query=system.string&product=vs&productversion=100&lcid=1033

But note that for offline URLs you can complete ignore the language parameter. It's enough to just specify "&product=VS&productVersion=100".

Update 3/3/2010: Apparently LCID currently only supports the 4 or 5 digit common LCIDs like 1033. It does not support the hex variation.
MS added this as a request from the VS IDE team. Generally MS recommend using the locale parameter instead.

BITS - Background Intelligent Transfer Service

The update & download technology used to bring down help packages from the Microsoft Server is called BITS, the same technology used by Windows Update.

There is a BITS API available for win32 and .NET programmers to use. 
If you are interested I found this article on using the BITS API 

Branding package

The branding package provides the default style, layout, transforms and scripting for a catalog's topics. When your topics are marked "microsoft.help.selfbranded=false" you use the default MS branding package with the MS Feedback link, MS (c) Copyright message and VS logo etc.

It's important to note that for version 1.0 the branding package applies to catalog level. So at the moment you couldn't integrate into VS\100\en-us and apply your own branding package to just your books and packages. However you could set Branded=false (in your topics) and set up your own branding using CSS, Script and images (in the normal way).

A few will want to create their own catalogs. In this case you can apply your own branding package if you wish.
To do this you would copy & modify the existing MS branding package. Remember a .mshc file is actually a ZIP file.

C:\Program Files\Microsoft Help Viewer\v1.0\Help3Branding.mshc
C:\Program Files\Microsoft Help Viewer\v1.0\Help3Branding-IE6.mshc

You setup a branding package via the HelpLibManager.exe command line.

"%programfiles%\Microsoft Help Viewer\v1.0\HelpLibManager.exe"
    /product MyCatalog /version 10 /locale en-us /brandingPackage dev10.mshc

Last time I looked at this you were required to copy your branding package into the store and use a relative path. This information is probably out of date. Looks like the command switch is undocumented so let myself or Paul know if you want more info on branding packages. MS will publish documentation soon.

You will notice there is a Help3Branding-IE6.mshc branding package in the help folder as well.
This is used to get around some of the layout quirks of IE6.  Note that you can't specify a -IE6 .mshc on the command line, however if a file named *-IE6.mshc is found it will be used.

Overriding the Viewer

VS users have been very vocal about the lack of Index and full TOC in this first release.
We are slowly getting the message out there that hooking up a substitute viewer (such as H3Viewer) is trivial.

You just need to set the registry item HelpViewerProgID=<ViewerPath> and Help Viewer 1.0 will direct all help calls to the alternative viewer. This includes Visual Studio help calls.

Example 1: Set H3Viewer as the default viewer

HKLM\Software\Microsoft\Help\v1.0
HelpViewerProgID=c:\program files\Helpware\H3Viewer\H3Viewer.exe

Example 2: Set Google Chrome as the default viewer

HKLM\Software\Microsoft\Help\v1.0
HelpViewerProgID=c:\Users\Robert\AppData\local\Google\Chrome\Application\chrome.exe

New Viewers Available Soon

The MS Help team have been actively responding to feedback about the current viewer.
At the MVP Summit they talked to C++, C# etc groups directly showing off new help viewers.

I saw 2x viewers demonstrated. Both had an index and full TOC.
Ryan Linton [Lead PM] had put together an awesome viewer that docked right inside the VS 2010 IDE.
Ian Hollier [lead programmer] had done a nice standalone viewer written in C#. 

Both these viewer took just a few days to write the basics (similar to my H3Viewer).
It just shows you again how powerful the new help API is.

The viewers should be available as an optional download around the time of VS 2010 release.

For Programmers: Build your own Viewer

I hope to have a paper available soon that shows you how to embed help and write a full viewer of your own.

If you want a head start I can help with Delphi and C# code (Thanks Ian Hollier and Paul O'Rear).
Or wait a bit and I will upload Delphi and C# examples shortly.

Help Future 

I've been amazed at what has been achieved in the last 2 years. The initial plan was to use WDS (Windows Desktop Search) but that did not work out for various reasons, so the team actually wrote a brand new help engine from scratch. Ian Holier and his programmers have done an amazing job. I can make multiple help calls on a catalog of 1 million topics and get results back in under 300 milliseconds. Very nice. The Help API is the best we have ever had in a help system. Love it!

Due to the very tight time line, features such as content filtering did not make it into this first release. And the help system has several limitations that integrators will need to work around. 

The good news is the foundation is solid and we can expect updates after VS 2010 RTM ships.
For those who miss the full TOC and Index there will be Help Viewers available that you can bolt-on.

While in Redmond the MVPs also saw a number of validation and test tools demonstrated.
These too will hopefully become available to integrators sometime after release.

Some Questions

Q. Can a book contain a combination of .CABs and .MSHC help files?
A. No. A mixture wont work.

Q. When will Help Viewer 1.1 ship and what can we expect?
A. Steady on, 1.0 isn't out yet. And the help team need a well deserved rest before they attack 1.1.


BTW a big thank you to Paul O'Rear, Charles, Sheridan and the rest of the help team for being such gracious hosts.
We had a great time learning about MS Help Viewer and giving you our feedback.

Happy snaps of the conference here: http://www.helpmvp.com/Home/photos/2010-summit

Rob




Comments