================================

Installing Content From Downloaded Help Viewer 2.0 cabs

This is a very simple and quick tutorial for creating a Help Viewer 2.0 MSHA. The MSHA is an XML file that describes a set of cabs. Help Viewer 2.0 can read the MSHA to obtain a list of content (the .CABs) available for local installation.

This is only a primer describing the very basic XML schema for the Help Viewer 2.0. There are additional elements which can be contained within the MSHA which this primer does not describe. For further information, reference the Help Viewer SDK (scheduled release date is TBD).

Note that there is an example implementation below this brief overview and sample HelpContentSetup.msha.

The name of the MSHA, for the purposes of this primer, must be HelpContentSetup.msha. The reason for this is that by default (the default installation), when looking for content on a local resource (local drive or folder) Help Viewer 2.0 looks for a file named HelpContentSetup.msha. HelpContentSetup.msha (example below) should contain a list of the cabs available. An easy implementation is to simply download the desired cabs to a folder, create an HelpContentSetup.msha (modified version of the below) and save that MSHA to the same folder that contains the downloaded .CABs. For each CAB, there should be a <div
class="package">…</div> (see example below). 

One last note – in the implementation example below, we have included the branding package cab. This is critical to include in order to get the needed Visual Studio content rendering elements and content behaviors. 

Sample HelpContentSetup.msha file (replace “cab name 1” and “cab name 2” etc. with the file names of the downloaded cabs):  

<html xmlns="http://www.w3.org/1999/xhtml">
<head />
<body class="vendor-book">
    <div class="details">
        <span class="vendor">Microsoft</span>
        <span class="locale">en-us</span>
        <span class="product">Microsoft Help Content</span>
        <span class="name">Microsoft Help Content</span>
    </div>
    <div class="package-list">
        <div class="package">
            <span class="name">cab name 1</span>
            <span class="deployed">False</span>
            <a class="current-link" href="cab name 1.cab">cab name 1.cab</a>
        </div>
        <div class="package">
            <span class="name">cab name 2</span>
            <span class="deployed">False</span>
            <a class="current-link" href="cab name 2.cab">cab name 2.cab</a>
        </div>
    </div>
</body>
</html>

Example Implementation: 

1. Create local folder, something like “C:\SampleDownloadedContentCabs”
2. Download desired cabs to the above folder:
1. Launch browser, Go to (copy and paste the following URL into the browser
   address field) http://services.mtps.microsoft.com/ServiceAPI/catalogs/visualstudio11/en-us
2. Download (select and save to folder created in step 1):
• v2visual_studio_2011_fundamentals_b906_vs_110_en-us_1(7df9cab6-4c1c-e5cc-5149-26f71459df93).cab
• v2visual_studio_2011_fundamentals_b906_vs_110_en-us_4(f881d128-d84e-70a7-989a-8b5a4808977b).cab
• VisualStudio_2011_Branding_en-US(08b345ee-bab5-517b-36cc-e0c486ca3962).cab
3. Create the below HelpContentSetup.msha as a txt file (I used Notepad to create the file) and save it to the above noted folder (see step 1) .
   1. Note that the class “name” value is the name of the cab file downloaded without the GUID (the string of characters within the parenthesis). This is important because the installation system uses this name to match the MSHC contained within the downloaded cab.
   2. Note that the class “Branding” exists and is unique.  The Branding cab is included in this primer so that the installed content will have branding, and the content behaviors that are contained in the downloaded cabs will have the appropriate support elements contained in the branding package cab.  Without this, errors will result when the system looks for support items that are not part of the ripped (installed) content.

<html xmlns="http://www.w3.org/1999/xhtml">
<head />
<body class="vendor-book">
    <div class="details">
        <span class="vendor">Microsoft</span>
        <span class="locale">en-us</span>
        <span class="product">Microsoft Help Content</span>
        <span class="name">Microsoft Help Content</span>
    </div>
    <div class="package-list">
        <div class="package">
            <span class="name">v2visual_studio_2011_fundamentals_b906_vs_110_en-us_1</span>
            <span class="deployed">False</span>
            <a class="current-link" href="v2visual_studio_2011_fundamentals_b906_vs_110_en-us_1(7df9cab6-4c1c-e5cc-5149-26f71459df93).cab">v2visual_studio_2011_fundamentals_b906_vs_110_en-us_1(7df9cab6-4c1c-e5cc-5149-26f71459df93).cab</a>
        </div>
        <div class="package">
            <span class="name">v2visual_studio_2011_fundamentals_b906_vs_110_en-us_4</span>
            <span class="deployed">False</span>
            <a class="current-link" href="v2visual_studio_2011_fundamentals_b906_vs_110_en-us_4(f881d128-d84e-70a7-989a-8b5a4808977b).cab">v2visual_studio_2011_fundamentals_b906_vs_110_en-us_4(f881d128-d84e-70a7-989a-8b5a4808977b).cab</a>
        </div>
        <div class="package">
            <span class="packageType">branding</span>
            <span class="name">VisualStudio_2011_Branding_en-US</span>
            <span class="deployed">True</span>
            <a class="current-link" href="VisualStudio_2011_Branding_en-US(08b345ee-bab5-517b-36cc-e0c486ca3962).cab">VisualStudio_2011_Branding_en-US(08b345ee-bab5-517b-36cc-e0c486ca3962).cab</a>
        </div>
    </div>
</body>
</html> 

1. The folder created in step 1 should now contain:
1. The 3 cabs downloaded in step 2 above
2. HelpContentSetup.msha created in step 3 above
2. Launch Help Viewer 2.0, select the Manage Content tab, and select the Disk button under “Installation source:”
3. Browse to the folder created in step 1 above, and select the HelpContentSetup.msha txt file created in step 3 above.
4. You should see a list of content to install. In the Action column, select add, which should create an entry in the Pending changes field. 
5. Once you have selected all the content you want to install, select the Update button, which will install the content to your local store (this last step will require local machine Administrator privileges which you will be prompted for during the installation process). 

Summary – Using and extending the above steps will enable the downloading of cabs to a local folder. In addition, an MSHA which describes the downloaded cabs (per the above) will enable installation of local Help content. This can be useful for customers who want to create DVDs of local Help content, customers behind proxy servers, and customers who manage networks where clients do not have access to the Internet. Note that the above is only a very simple start. The MSHA file has additional support elements, content can be packaged in MSHC’s, and branding packages can be extended. All these features of the Help 2.0 system will be defined in the forthcoming Help 2.0 SDK.

Please send feedback to hlpfdbk@microsoft.com!

At the time that we were getting all our bits ready to release to manufacturing for the //build conference, we did not yet have the Dev11 query service enabled on our MSDN Library site. As a result, the IDE is still pointing to the Dev10 query service both for Help | View Help and for F1 requests.

Since //build we have deployed the Dev11 query service, and you can now tweak your registry to point to that. << insert standard caveat here about modifying the registry yourself… :) >>

For Visual Studio 11 Developer Preview:

//32-bit
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\11.0\Help]
"OnlineBaseURL"="http://msdn.microsoft.com/query/dev11.query?appId=Dev11IDEF1&l="

//64-bit
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\11.0\Help]
"OnlineBaseURL"="http://msdn.microsoft.com/query/dev11.query?appId=Dev11IDEF1&l="

For Visual Studio 11 Express for Windows Developer Preview:

//32-bit
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VSWinExpress\11.0\Help]
"OnlineBaseURL"="http://msdn.microsoft.com/query/dev11.query?appId=Dev11IDEF1&l="

 //64-bit
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VSWinExpress\11.0\Help]
"OnlineBaseURL"="http://msdn.microsoft.com/query/dev11.query?appId=Dev11IDEF1&l="

If you were running Visual Studio when you made these changes, shut it down and restart it. Now if you select Help|View Help or press F1, you will be directed to the Visual Studio 11 Developer Preview content.

There are a few topics in the new Windows 8 DevCenter that give an idea of the current thinking around Help in Metro apps and the idea of an Help "charm".

Check out Adding app help, which is the starting point.

Hopefully, by now, you've been hearing a lot of buzz about what is coming in Windows 8 and some great developer experiences coming in Visual Studio 11. Lots of this has been demo'd at the //build conference this week.

You can view the //build conference keynotes here:
https://channel9.msdn.com/Events/BUILD/BUILD2011

You can even download the Windows 8/Visual Studio 11 Developer Preview bits here:

• Download Visual Studio 11 Developer Preview (MSDN Subscribers only)
• Download Visual Studio 11 Developer Preview (general availability on September 16, 10am PDT)

Jeff Braaten from my organization has done a nice summary of some of the new things you can expect from Help Viewer 2.0 on Third Blog from the Sun.

Some highlights:

• Switch from online to offline and back with a simple menu option in the VS IDE
• Help Content management and updates now built directly in the Help Viewer (no need to re-launch viewer, etc.)
• No more tray app
• Lots of performance improvements
• Advanced Search operators - title: and code: (these are a personal favorite!)
• The Visual Studio Help runtime is now the Windows 8 Help runtime!

Just to be really clear about that last point - it is the Help runtime from Help Viewer 2.0 that is in Windows 8 and not the viewer itself. Windows has their own Help experience that they drove off the work we've done on the help runtime. So while this is not the ".chm killer" so to speak, it is good progress.

There are many other features that have been getting baked into Help Viewer 2.0 that will more clearly come online as we get closer to Beta and RTM. Some are true innovations in Help experiences in my (not so humble) opinion. Jeff aludes to some of these as filtering features in his post. Others will particularly light up a number of Visual Studio Industry Partner (VSIP) and localization scenarios. Stay tuned as we move towards Beta and RTM for more details.

As always - let us know what you think!

• Leave a comment at the bottom of this blog post (or contact me via this blog)
• Send us an email at hlpfdbk@microsoft.com
• Share your thoughts on the Developer Documentation and Help System Forum

You can download and install Visual Studio 2010 SP1 from here.

You can also check out the video I posted about SP1 Help Viewer recently here.

Try it out and let us know what you think! We're getting there, a step at a time!

We have been hard at work over the last several months since Visual Studio 2010 was released. Over the beta period prior to release and since the release, we have had a significant amount of feedback driving for a more familiar Help experience to what we shipped in previous versions of Visual Studio. To that end, we have been developing an offline client help viewer - similar in some respects to Document Explorer (Dexplore.exe) that shipped with previous versions of Visual Studio.

Jeff Braaten, Director of Program Management for the Library Experience team which owns the Visual Studio Help Experience, has posted 3 blog posts today that both tell the story of how we got to where we are today and highlight some of the changes that you should expect to see in SP1. You can read the whole story, or go directly to the SP1 specific post.

The video we posted is me giving a brief demo of an early build of the new Help Viewer for Visual Studio 2010 SP1. A slightly more Channel 9 friendly version of the video is also available.

What does this mean for Visual Studio Industry Partners (VSIPs)?

We expect this should be a net gain for partners, with no new work required for them nor their customers to take advantage of the update beyond installing SP1.

Q: Do we need to do anything differently with our content than we did for Visual Studio 2010 RTM to get it to display in the new viewer?

No. The general requirements for integrating your help content with Visual Studio 2010 have not changed. Please see our Getting Started with Help Content and Integration for Visual Studio 2010 if you are new to these requirements.

Q: Are we able to customize how our content is branded in the new viewer?

Yes. The new viewer still supports the content branding features that are documented in the Help Viewer 1.0 SDK.

Q. Are we able customize how the new viewer itself is branded (“skinning”).

No. Our focus for SP1 was to ensure that customer productivity was restored in a number of key areas, as described in the video and Jeff Braaten’s blog posts.

Q. How will our content appear in the Table of Contents in the new viewer?

One of the things we heard most about from partners was the diminished discoverability of their content with Visual Studio 2010 RTM release. With the new viewer, we have restored the familiar treeview type of experience with the Table of Contents (TOC) so that no matter how you enter the TOC, 3rd party content will always be visible and accessible as in earlier versions of Visual Studio.

Q. What if the user’s default setting is to go Online?

The behavior is essentially the same as it was at VS 2010 RTM.

If the user’s default is set to Online, then a browser is launched to MSDN Online and 3rd party content is not visible, because it is not hosted or otherwise available via MSDN Online.

If a user issues an F1 help request, and 3rd party content is installed locally, we will open the local help for that content request for 3rd party partner content as we did at VS 2010 RTM.

If you have additional questions – feel free to post them and I will add responses to the list here.

We would very much welcome your feedback. Feel free to drop me a line here via the blog, leave comments on either my or Jeff’s blog, or send mail to our Help Feedback alias – hlpfdbk@microsoft.com).

We look forward to hearing from you!

What is Microsoft’s guidance regarding:

• WinHelp (.HLP files)
• HTML Help (.CHM files)
• Assistance Platform 1.x (.H1S files)
• Microsoft Help 2.x (.HxS files)
• Help Viewer 1.0 (.MSHC files)

Here is an high level summary of our position on the help formats listed above (see below for further discussion):

1. If you are developing a general Windows application today, it is our recommendation that you use HTML Help (.CHM files), and not WinHelp (.HLP files).
   • HTML Help ships as part of the Windows OS.
   • WinHelp viewers compatible with Windows Vista and Windows 7 are available for download.
2. If you are an Original Equipment Manufacturer (OEM) and need to produce documentation to integrate with Windows Help and Support for Windows Vista or Windows 7, you need to develop content that works with Assistance Platform 1.0 (.H1S files).
3. If you are a Visual Studio Industry Partner or shipping a product that extends Visual Studio 2010, you need to develop content that works with Help Viewer 1.0 (.MSHC files). Help Viewer 1.0 ships with Visual Studio 2010.
4. If you are a Visual Studio Industry Partner or shipping a product that extends earlier versions of Visual Studio (2002 – 2008), you need to develop content that works with Microsoft Help 2.x (.HxS files). Microsoft Help 2.x ships with Visual Studio 2002 – 2008.
5. Assistance Platform 1.0, Microsoft Help 2.x and Help Viewer 1.0 are not available for general 3rd party use or redistribution.

If you are developing a general Windows application today, it is our recommendation that you use HTML Help, and not WinHelp. The information on the following pages is still generally applicable: Application Compatibility: Help Engine Support and Which Version of Help Do I Need?

If you haven’t already, moving from HLP to CHM would be a good decision at this time. Your biggest hurdle in moving from HLP to CHM is the migration of your content from RTF to HTML. The HTML Help Workshop has some rudimentary tools to help you in migrating your projects over to HTML  and CHM. You will likely need to do some additional work to get your content to look a bit more polished than what the conversion tool will produce.

If it’s within your budget, you may wish to consider adopting a formal Help Authoring Tool (HAT). Most of the better known HATs will allow you to import an HLP project and output an HTML Help/CHM file. A good place to compare options is the HAT Matrix maintained by one of our Help MVPs, Char James-Tanny.

HTML Help ships as part of the Windows OS.

Customers on Vista and Windows 7 can download the WinHelp viewer (for.HLP files) from our download site.

• Vista
• Windows 7

Assistance Platform 1.0 (.H1S files):

The Assistance Platform format is only used by the Windows operating system and OEMs for OS customization. The documentation and tools for compiling this format are part of the Windows Automated Installation Kit (AIK) available for download. The Assistance Platform Client (helppane.exe) and its format are not available for general 3rd party use or redistribution.

• Vista (WAIK); User’s Guide
• Vista SP1 and Windows Server 2008 (WAIK)
• Windows 7 (WAIK); Documentation

For further general information, see Assistance Platform 1.0 Client SDK on the MSDN Library site.

Microsoft Help 2.x (.HxS files):

If you are a Visual Studio Industry Partner (VSIP) or shipping a product that extends earlier versions of Visual Studio (2002 – 2008), you need to develop content that works with Microsoft Help 2.x. Microsoft Help 2.x ships with Visual Studio 2002 – 2008. The Microsoft Help 2.x runtime, Document Explorer (dexplore.exe) and its format are not available for general 3rd party use or redistribution.

For information about Microsoft Help 2.x, the .hxs file format and integrating Help with Visual Studio 2002 – 2008, please visit the Visual Studio 2008 Help Authoring and Integration page.

Help Viewer 1.0 (.MSHC files):

If you develop a product that integrates with Visual Studio 2010, or re-uses the Visual Studio 2010 IDE as part of your own product then you are able to take advantage of Help Viewer 1.0. The Help Viewer 1.0 runtime is not available for general 3rd party or redistribution. The file format and attribution is non-proprietary.

For more information about Help Viewer 1.0 with links to an SDK documenting the MSHC file format and integrating Help with Visual Studio 2010, please visit the Visual Studio 2010 Getting Started with Help Content and Integration page.

Feedback is welcome!

This list is also not exhaustive by any means. I will add additional links and blurbs as I get them or find them.

A few such sites that I'm closely aware of because of my interaction with the Microsoft Help MVPs are:

Help MVP site

This is a site owned and run by the Microsoft Help MVPs themselves. There are at least two entry points

1. main page with general info about the Help MVPs and some related links
2. mshcMigrate page with lots of great info about the new Help Viewer 1.0 release from Microsoft.

JTF Associates' HAT-Matrix.com (Char James Tanny)

Char says the following:

When you are looking for an authoring tool, be sure to include HAT-Matrix.com in your research. Start with the blank report (http://hat-matrix.com/blank_report_2.html) and select the features that matter most to you. Save the finished report and use it to determine which applications you should put on your “short list”. You can also compare features from the authoring tools included in HAT-Matrix by producing different reports. Visit http://www.hat-matrix.com.

The Helpware Group (Rob Chandler)

Rob says the following:

First established in 1996 The Helpware Group produces quality software that supports the various Microsoft Help technologies. The group is based in Melbourne Australia and headed by Help MVP Robert Chandler. 

The Helpware web site contains many technical articles, tutorials and FAQ on MS Help technologies, Delphi and C#. Helpware’s mshcMigrate tool allows you to quickly migrate older help to Visual Studio 2010 help. H3Viewer is a free replacement viewer for VS 2010 Help. See all Helpware shareware products here: http://helpware.helpmvp.com/products

Finally, a new resource that I've been made aware of from Marc Achtelig of indoition engineering:

indoition.com (Marc Achtelig)

Marc says the following:

In addition to about 250 useful links for technical writers, the site for example provides checklists and up-to-date market surveys of more than 350 help authoring tools, screen capture tools, screencasting tools and other utilities for technical communicators. All information can also be downloaded as a PDF booklet (approx. 100 pages). The URLs are:

http://www.indoition.com/index.html

http://www.indoition.com/online-help-authoring-tools-survey.htm