The Help Guy

Installing Content From Downloaded Help Viewer 2.0 cabs

Paul ORear MSFT — Tue, 10 Apr 2012 20:03:00 GMT

Today I have a guest post from my good friend and co-worker in the Help Viewer team, Malcolm Dickson. Malcolm describes how you can create a 'local' means of installing content for scenarios behind firewalls or where there is no Internet connectivity. It still requires the ability to download content as the initial starting point, but allows you to create your own install script from downloaded content. Send your comments to hlpfdbk@microsoft.com!

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

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):

Example Implementation:

Create local folder, something like “C:\SampleDownloadedContentCabs”
Download desired cabs to the above folder:

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
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

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>

The folder created in step 1 should now contain:

The 3 cabs downloaded in step 2 above
HelpContentSetup.msha created in step 3 above

Launch Help Viewer 2.0, select the Manage Content tab, and select the Disk button under “Installation source:”
Browse to the folder created in step 1 above, and select the HelpContentSetup.msha txt file created in step 3 above.
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.
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!

Hook Up Visual Studio 11 Developer Preview and Visual Studio Express for Windows Developer Preview to Visual Studio 11 Developer Preview content on MSDN

Paul ORear MSFT — Wed, 21 Sep 2011 23:58:00 GMT

I hope you’ve been having fun exploring the new features of both Visual Studio 11 Developer Preview and Windows 8 Developer Preview!

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.

Help "charm" in Windows 8 Metro apps

Paul ORear MSFT — Fri, 16 Sep 2011 19:45:42 GMT

If you've been watching the developments from the //build conference and Windows 8 preview, you might have wondered what the Help story is for Metro apps...

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.

Help Viewer 2.0 + Visual Studio 11/Windows 8 Developer Preview

Paul ORear MSFT — Thu, 15 Sep 2011 18:35:33 GMT

I've been rather quiet lately - but for good reason! (We've been really busy!)

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:
http://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

VS 2010 SP1 Beta now available - including new client Help Viewer!

Paul ORear MSFT — Sat, 11 Dec 2010 01:25:00 GMT

Please check out my boss Jeff Braaten's blog regarding our new client help viewer now shipping with VS 2010 SP1 Beta. You can find some info there on installing the SP1 and how best to explore the new viewer experience if you've been using some other alternatives, like Helpware's H3Viewer.

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!

Help Viewer 1.1 Preview Video

Paul ORear MSFT — Wed, 27 Oct 2010 17:59:00 GMT

I’m excited to announce that we have just posted a preview video of Help Viewer 1.1, which will be shipping with Visual Studio 2010 SP1.

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!

Help State of the Union (October 2010)

Paul ORear MSFT — Tue, 26 Oct 2010 18:29:00 GMT

Periodically, questions come to Microsoft via a variety of avenues regarding our current guidance on Help systems and formats. And they usually end up in the Help Guy’s inbox. :)

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):

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.
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).
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.
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.
Assistance Platform 1.0, Microsoft Help 2.x and Help Viewer 1.0 are not available for general 3rd party use or redistribution.

WinHelp (.HLP files) and HTML Help (.CHM files):

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.

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.

Fixed Help SDK download now available

Paul ORear MSFT — Wed, 01 Sep 2010 18:02:57 GMT

Thanks for everyone who helped us identify the issue with our original download. We have rebuilt and tested the package and re-uploaded it to the SDK download page. Please redownload the package and you should be good to go. Thank you for your patience!

Help Viewer 1.0 SDK now available!

Paul ORear MSFT — Fri, 06 Aug 2010 21:45:53 GMT

It's been a long time coming, but we have finally released the Help Viewer 1.0 SDK. It can be downloaded here.

Feedback is welcome!

Help-related resource pages

Paul ORear MSFT — Thu, 05 Aug 2010 19:08:00 GMT

Since starting this blog, I've had a few requests to post links to various software products and resource pages for Help related authoring tools and services. I think this is a great idea. My posting these is explicitly not any kind of Microsoft official endorsement, but just giving a shout out to a variety of resources that you may find useful.

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

main page with general info about the Help MVPs and some related links
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

EC Software's Help & Manual now supporting Sandcastle

Paul ORear MSFT — Thu, 01 Jul 2010 18:56:00 GMT

This just in from Tim Green @ EC Software, GmbH:

Just saw your posts and the announcements about the new Sandcastle developments, that's great to hear! We also have some big Sandcastle news: As of version 5.4 Help & Manual now supports Sandcastle. You can import a Sandcastle project to Help & Manual directly. When you do this, HM runs Sandcastle and redirects its output, converting it to a Help & Manual XML project on the fly. You can then edit (also multi-user) and publish in Help & Manual, with support for Help & Manual's output formats, including CHM and PDF. There's also a mechanism for handling updated Sandcastle projects when you import a Sandcastle update to a project created with an earlier version of the Sandcastle project.

Just a note of clarification that Help & Manual 5.4 currently supports the Visual Studio 2002-2008 Help 2.x format (.HxS), but Visual Studio 2010 Help Viewer 1.0 format (MSHC) is still pending.

You can contact Tim @ EC Software using support@ec-software.com, as well as via their user support forum, http://helpman.it-authoring.com.

Re-post: Helixoft VSDocman adds support for VS 2010 Help

Paul ORear MSFT — Thu, 01 Jul 2010 17:42:56 GMT

(It appears during forum migration this post got deleted from my blog - so re-posting...)

I'm glad to report today (originally posted 5/19/2010) of another Help Authoring Tool (HAT) vendor to add support for the MSHC format used by Visual Studio 2010. Here is a small blurb from Peter Macej of Helixoft:

VSdocman is a VS add-in for commenting and the automatic generation of class documentation from your C# and VB .NET source code. VSdocman parses the Visual Basic and C# projects (including ASP .NET) and automatically creates MSDN-like documentation, IntelliSense and F1 context sensitive help. You can edit your XML comments with WYSIWYG comment editor which allows inserting complex tables, links, pictures, class diagrams and others. Predefined output formats are HTML Help, MS Help Viewer, Help 2, HTML, RTF, Help&Manual and XML. Contact and other information can be found on product page.

Click here for more information about additional HAT solutions that support MSHC.

Sandcastle with MSHC support has been released!

Paul ORear MSFT — Thu, 24 Jun 2010 19:30:00 GMT

I'm pleased to announce that we have posted a release of Sandcastle that now supports the MSHC Help file format used by Visual Studio 2010.

The MSHC support was commissioned from ComponentOne, whom we thank for updating the code base to support this new Help format. We have additionally rolled in a variety of bug fixes since the last release in 2008. Please note the MSHC Usage Notes and Changes/bug fixes documentation links on the download site.

MSHC support is currently limited to reproducing the VS 2008 look and feel and functionality within the VS 2010 Help Viewer. To achieve parity with VS 2010 look and feel will require more work and we encourage enterprising folk out there to take this on and contribute to the code base.

Have you heard about the Preview of MSDN Online Updates?

Paul ORear MSFT — Tue, 22 Jun 2010 23:45:00 GMT

If you've worked for any time at all with the .NET Framework and have looked up documentation in the MSDN Library, you've likely noticed a very lengthy section under "Class Library" in the Table of Contents. The .NET Framework now contains so many namespaces and classes that your eyes likely blurred over when you saw the long list of System.* namespaces and tried to find the one you were looking for. Additionally, you may have often wondered what the purpose was of having a separate Overview page for a class, from a list of all its Members, etc.

We've been batting around some ideas for quite a while about how to improve the experience with this particular content, and are now taking a cut at implementing some of them. We would absolutely love your feedback about what works for you and what does not - and why!

There's an overview of the changes available at Kim Wolk's blog here. Please note that Search particularly does not work from the links noted in her blog - this Preview is a Beta site and not intended to be fully functional.

Additionally, Scott Guthrie, Corporate VP and overall .NET Guru, has done a wonderful write-up as well. There's lots of lively discussion there... Check it out!

Updating multiple VS 2010 installations' Help content with a single download

Paul ORear MSFT — Thu, 29 Apr 2010 23:25:00 GMT

A question that we've begun to see come up from folk that have generally low-bandwidth is whether there is a way to download updates once for one machine and to then use that content for other machines as well.

One customer puts it this way:

"Also, while the updating feature is great, the downloads appear quite large and if you have a number of machines to update then this can be a slow and bandwidth consuming task, is there any way to download and share the help system updates between multiple installations?"

We do not currently support a way to do this seemlessly through our Help Library Manager dialog, but there is a way you can work around this if you are a network admin for example, and the machines you are administering are pretty much all configured the same way with the same general drive designations. e.g. For all systems, you have chosen to create your Local Store for VS 2010 Help content to be at the same path location.

My friend and Library Experience teammate, Charles Christian, has written some excellent comments about a related issue on some of our developer forums, which I'll alter slightly and summarize here:

On a single machine, launch Help Library Manager from the Visual Studio 2010 IDE using Help | Manage Help Settings

Install and update any content that you wish to be available on all other machines using Help Library Manager.

Open the settings screen from Help Library Manager, by clicking on the Settings link on the upper right. Note the path of the Local Store that should appear grayed out in the lower half of the dialog. The default path if you did not change anything during setup would be: %ALLUSERSPROFILE%\Microsoft\HelpLibrary. In Windows 7 this will probably translate to C:\ProgramData\Microsoft\HelpLibrary.

On any other machine that you wish to update with the same changes

Ensure that the Help system is closed down - close any browser that may currently be displaying local help. Ensure that you are not running Help Library Manager and that the Help Library Agent is also closed down (right click on the Help Library Agent tray application and select Exit).

Copy the entire Help Library folder from the first machine over to the same location on the machine you wish to update.

Please note that this is not a supported scenario. We recommend taking a backup before proceeding with these steps! Please note also that you will need to have Admin privileges on any machine that you wish to perform this operation.

Clever workaround for getting dynamically inserted javascript or stylesheets to work in Help Viewer 1.0

Paul ORear MSFT — Tue, 23 Feb 2010 23:20:00 GMT

Working with our Visual Studio 2010 (and earlier!) partners, I'm frequently impressed with the ingenuity they demonstrate in just getting things to work. Even though Help systems these days are generally HTML based, there are often some gotchas that come up that are generally limitations due to an implementation.

With Help Viewer 1.0, one of the current limitations is that when .js or .css files (and other resources in general) are referenced, they essentially need to be hard coded in the topic in order for them to work. The reason for this is that just prior to loading and rendering the topic, the Help runtime does some transforms on the content to fix up the paths so that they are able to be extracted from our MSHC file format. (Just renamed .zip files.)

What if you want to dynamically reference a .css or .js file depending on the context of the topic itself? For example, suppose the exact same topic is meant to be used in a .CHM or .HxS file, or even possibly on a website? In general, this is currently not supported in Help Viewer 1.0. The reference that would be inserted would not happen until after our transforms are applied, and therefore the path to the .css would not express the full path into the MSHC. It would just not get used at all.

Richard Sloggett at Innovasys worked out an ingenious solution that he is leveraging in their Document!X and HelpStudio Pro authoring tools, and has kindly agreed to let me share it with the community. Here's what he writes:

Here’s the core function to get the resource base url - it relies on having a named script element – e.g.

<script id="mshs_support_script" src="scripts/mshs.js" mce_src="scripts/mshs.js" type="text/javascript"></script>

That script element can be anything – it’s just there to discover the store root. Just then append the relative bit (e.g. ResourceBaseUrl + ‘myscript.js’) when adding the new script.

/* Gets the MSHS base url for resources */

function ResourceBaseUrl() {

    if (isDesignTime) {

        return '';

    }

    else {

        // Get the first script tag

        var script = document.getElementById('mshs_support_script');

        // Extract the src which is a full resource url to within our origin .mshc

        var scriptSrc = script.src;

        // Get the portion up to the ; (the base url for resource references)

        var startIndex = scriptSrc.indexOf(';') + 1;

        var scriptUrl = scriptSrc.substring(0, startIndex);

        return scriptUrl;

    }

}

Brilliant! Thanks Richard, for allowing me to share this with the community.

Partner Content Discoverability Options in Visual Studio 2010, Part II: Shortcuts

Paul ORear MSFT — Tue, 16 Feb 2010 21:08:00 GMT

One of the side benefits of the F1 feature I wrote about the other day is that vendors can effectively create VS IDE Help menu and Start menu shortcuts to their own documentation that will always work, regardless of the end-user's online/offline preference.

The VS 2010 Documentation shortcut looks something like this:

ms-xhelp:///?method=f1&query=msdnstart&product=vs&productVersion=100&locale=en-us

This is just a call to our query API and can be used anywhere once Help Viewer 1.0 is installed.

3^rd party integrators can essentially replace that ‘msdnstart’ keyword highlighted above with an F1 keyword that maps to perhaps a portal page in their own content. This would then result in Help being opened up to the Partner content page, again regardless of the end-user’s online/offline state.

Creating an item on the Help menu in the IDE is accomplished by using the method described in VSPackage Tutorial 1: How to Create a VSPackage.

The wizard will result in creating a menu item on the Tools menu and will be defined in a MenuCommandsPackage.vsct file. To get your menu item to show up on the Help menu, look for the following item in this file:

<Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>

</Group>

and replace the Parent element with:

You can also adjust the string that is used for your menu item and the bitmap that is displayed through entries in this same file.

Finally, to hook up the menu item to your help topic, there should have been a MenuCommandsPackage.cs (or similarly named file) added to your solution after completing the wizard. The methods are stubbed out with message box code to help you prove to yourself that your menu is running. After following the steps I described on this page for adding references for the IVsHelp interfaces, you can add a pretty straightforward call to a page in your content.

private void MenuItemCallback(object sender, EventArgs e)
{

Help help = (VsHelp.Help)GetService(typeof(SVsHelp));

help.DisplayTopicFromF1Keyword("VS.DevPartner.ReportGen.Settings");

}

Partner Content Discoverability Options in Visual Studio 2010, Part I: Context Sensitive Help (F1)

Paul ORear MSFT — Wed, 10 Feb 2010 00:49:00 GMT

If you haven't seen the announcement about the Visual Studio 2010 RC release - check out this page. The Visual Studio 2010 RC is immediately available to all comers.

As we’ve been working our way towards RTM we’ve had lots of invaluable feedback from our partners and our Help Authoring Tool vendors that have had keen eyes toward partner scenarios.

With Visual Studio 2010 and Help Viewer 1.0 we made a conscious decision to make Online the default for most Help related scenarios. In this scenario, we make the calls and experience as efficient as possible by pushing the query directly to our online query service and hosting the entire Help experience from MSDN Online.

Since partner content is not available in MSDN we needed to work out a means to make partner content discoverable, which by definition would be offline content (at this time) when the user’s default was set to Online.

The scenario can be summarized:

an end-user installs a 3rd party component or add-in along with its help content, and
the end-user's default for Help and F1 lookups is set to Online
What happens when a user presses F1 when a partners control or add-in is in focus?

Since the entire Online Help experience is managed directly from MSDN Online, that experience inherently has no knowledge of a user's local machine state. The end-user would effectively never see or know that there was Help content available for the 3rd party component or add-in.

We clearly wish to enable partner content to be accessible in all contexts, and you all have helped us think through ways we could enable this.

As of this RC build, we will do a very quick query on local *vendor* content to determine whether there is a topic that matches the F1 keyword query. If there is a hit, then we will take the user directly to the local vendor content rather than looking on MSDN Online and giving a 404.

We manage content from all vendors (including Microsoft) separately. This will potentially enable a number of useful Online content scenarios in the future, but the fortunate benefit *now* is that we are able to distinguish between Microsoft and non-Microsoft content. And therefore, enable a different behavior for partner content.

I plan to post a discussion on how we’re beginning to look at partner content discoverability scenarios moving forward from Visual Studio 2010. Look for this in the next few weeks.

Thanks again to all our partners and HAT vendors who have helped us to think this through!

Download the RC and let us know what you think!

Some updates

Paul ORear MSFT — Tue, 02 Feb 2010 23:39:00 GMT

I added a few more items to the Known Issues page.

Also, a new page added: Calling Help Viewer 1.0 from VS add-in code. If you're developing add-ins for Visual Studio 2010 (or earlier actually), you may find this information handy. It describes the references necessary and basic steps for launching F1 help, whether with Help 2.x or Help Viewer 1.0.

Help Authoring Tool (HAT) support for Help Viewer 1.0

Paul ORear MSFT — Tue, 26 Jan 2010 20:29:00 GMT

As we've been ramping up the new the Help Viewer and its associated Help file format (MSHC), we've also been working closely with a few vendors to ensure that we have a good Help Authoring Tool (HAT) story for Visual Studio 2010.

We have been working principally with the vendors that have historically been supporting Visual Studio's help system in the past (with Help 2.x). We are excited about the long-term growth potential of our new help system and welcome engagement with other HAT vendors as well. If you are in that category, please contact me via the contact form and I'll be glad to follow up with you.

Below are listed the current Help Authoring Tool (HAT) vendors that currently support the Visual Studio 2010 Help format (MSHC). I have collected a little statement from each about their offering and how best to contact them at this time. They are listed below in alphabetical order for convenience sake (no indication of preference or quality, etc. implied):

ComponentOne, LLC:

"Doc-To-Help has always had a close relationship with Microsoft and the MSDN user community. You will always enjoy support of Microsoft’s latest technologies from their standard Help platforms to .NET developer technologies such as Help 2.0, Sandcastle, and .NET/XML transforms.

Doc-To-Help will also always serve the community’s needs by addressing and supporting emerging technologies such as Visual Studio 2010, Microsoft Help Viewer 1.0, and beyond.

If anyone is interested in a beta version of Doc-To-Help 2010 that works with MS Help Viewer, please contact Brad Keller at ComponentOne: bradk@componentone.com." Brad Keller - ComponentOne, LLC.

Helixoft:

VSdocman is a VS add-in for commenting and the automatic generation of class documentation from your C# and VB .NET source code. VSdocman parses the Visual Basic and C# projects (including ASP .NET) and automatically creates MSDN-like documentation, IntelliSense and F1 context sensitive help. You can edit your XML comments with WYSIWYG comment editor which allows inserting complex tables, links, pictures, class diagrams and others. Predefined output formats are HTML Help, MS Help Viewer, Help 2, HTML, RTF, Help&Manual and XML. Contact and other information can be found on product page." Peter Macej - Helixoft

The Helpware Group:

"mshcMigrate was developed by The Helpware Group in partnership with Microsoft and allows you to migrate older help content (MS Help 2 and MS HTML Help 1.x) to MS Help Viewer format (the new format for MS Visual Studio 2010 help). It takes various inputs including projects files (.hxc and .hhp), compiled help files (.hxs and .chm), and help folders. Outputs include .mshc/.cab help package files and .msha manifest files. The application includes several additional tools that allows you to test, install/uninstall, view the HelpLibManager.exe output log, perform API calls, and explore the help library data store. The utility is part of Helpware's FAR HTML v5 product set which provides advanced meta tag editing and TOC/Index editing for MS Help Viewer projects. mshcMigrate however can be downloaded separately and is free for personal use (see mshcMigrate licensing for further detail). Contact and support details can be found on the download page." Robert Chandler - The Helpware Group

Innovasys, Ltd.:

"Innovasys are currently finalizing updates to Document! X and HelpStudio to support seamless multi-targeting of Help 2.x (VS 2002 - 2008) and Microsoft Help Viewer (VS 2010) for both reference (assembly SDK docs) and conceptual documentation. Contact support@innovasys.com if you would like to take part in the beta." Richard Sloggett - Innovasys, Ltd.

Sandcastle:

Many people have been asking about whether we will be updating the Sandcastle toolset to support Help Viewer 1.0. I'm pleased to announce that we have posted a release of Sandcastle that now supports the MSHC Help file format used by Visual Studio 2010.

What are we trying to accomplish with code signing content?

Paul ORear MSFT — Sat, 23 Jan 2010 03:31:00 GMT

Help file content and web content have historically been significant attack vectors that hackers and viruses have utilized quite a bit over the last decade. We’ve seen significant issues with .CHM security issues since HTML Help 1.x was released. HTML based attacks in general are huge - we had a hack against our TechNet site just yesterday.

So how do we prevent this sort of thing – even though the TechNet issue is a web specific example. Here are some of the constraints:

· If anyone with minimal privileges can install or be tricked to install content with dangerous scripts, an Admin could potentially run unsafe content. On machines that are shared between multiple users, a user could unknowingly execute script that may have been installed by another user with lower execution privileges. In a review with the Windows Security group, they warned against the dangers of this scenario.

· Even with Admin privileges, Admins don’t always understand the implications of what they are installing, so we still wish to provide notification that the action they are about to take is potentially unsafe.

· With Self-branded content, there's higher risk of script being executed that is potentially unsafe – this, for us implies an even higher risk that we’ll need to protect the user against.

· With Help Viewer 1.0 we are ultimately aiming at a broader user base than just Visual Studio users. We would like to become a replacement for both WinHelp and HTML Help 1.x.

If you look at how security is managed for WinHelp today, its primary attack surface is around its macro capabilities. This is why in Vista and Win7, macros are completely disabled by default. You have to be an Admin to update the registry with some reg keys in order to re-enable these features.

Additionally, with HTML Help 1.x, check out this list on Microsoft Help MVP Rob Chandler’s site:

http://helpware.net/FAR/far_faq.htm#SecurityUpdates

For better or worse, there’s a whole lot of security restrictions on help files now. The difference you may argue is that these are generally mitigated when a user installs a .chm via a setup program.

The primary difference we have with Help Viewer 1.0 however is that a user can install content from media or the cloud, as well as updating from the cloud. Currently, this is mostly for Microsoft content, but we are not architecting to limit it to MS only content.

· We ideally wish for a secure mechanism for installing and updating content regardless of the source location.

· We need a mechanism that as a starting point helps guarantee against unsafe script being executed unintentionally, or at least with full knowledge that you’re opening yourself up for that.

I think we agree that this is a pain (perhaps a necessary evil), and we’re open to discussion for how we might better address this in SP1, for example. Maybe the Admin applied reg key solution like WinHelp and HTML Help employ would be OK. I think what we’re trying to get across though is that, as its apparent with all the UAC hoopla around Vista and Win7, we unfortunately live in a general “unsafe” age and at a platform level we need to both educate users about the potentially unsafe actions they are about to take, and where possible prohibit if they are not in a position to make that kind of evaluation.

How would you provide strong security given these constraints?

Working with signed .cab files

Paul ORear MSFT — Fri, 22 Jan 2010 00:38:00 GMT

There's been a fair amount of discussion both in private emails and on the MSHelp3 Yahoo! group about the pros and cons of requiring signed .cab files for silent installs with the new Help system.

As anyone who's been using Vista and Windows 7 knows, security is a pretty big deal these days despite all the headaches people feel it causes. Without security, you'll have even bigger headaches before you know it!

Before long I will be posting some background on some of our thinking around this requirement. In the meantime, however, I wanted to make sure that those who have need of some of the basic details around signing their cab files have access to the general details.

In addition, I'm providing some information about what you can do to test this out without having to purchase a certificate - you can create your own test certificate, which you can use for signing purpsoses on your own machine.

Here's a page (again in the Links section, as well) describing the basic process. Have fun!

Known Issues

Paul ORear MSFT — Thu, 21 Jan 2010 02:16:00 GMT

There are a handful of "known issues" with Help Viewer 1.0 that we will be shipping with at VS 2010 RTM.

I will be maintaining a list of these issues and any updates via a page off the Links page.

Which IVsHelp Interfaces are supported in Visual Studio 2010?

Paul ORear MSFT — Wed, 20 Jan 2010 22:15:00 GMT

Please see my page posted here.

As I publish new pages, they will all be easily accessed via the Links link in the left-hand navigation pane.

Welcome!

Paul ORear MSFT — Mon, 18 Jan 2010 23:06:00 GMT

Hello and welcome to “The Help Guy” blog!

Why “The Help Guy?”

I was aiming for just “Help Guy”, but it was already taken, though not accessible for some reason. Hmmm. Not very helpful.

For me, THE Help Guy will always be Ralph Walden. I call him “The Father of Help” – primary driver and developer of the 3 main help systems that have had Microsoft platform-wide use to this day: QuickHelp (used in 1980’s DOS products, like the original Microsoft C++ Programmers Workbench, etc.), Windows Help (aka. WinHelp), and HTML Help 1.x. He even worked on the OS2 Help system while Microsoft was still involved with that OS.

I could have gone with – wait for it – Ivory Boy. Nan Hickman, author of “Building Windows 95 Help” gave me this dubious appellation for some strange reason around 1995, back when Compuserve was still the rage and we had a lively WinHelp forum there. Ralph even gave me the perhaps more dubious distinction of naming an internal HTML Help system file after me: #IVB – used for storing Alias string information for context sensitive help purposes (See this interesting article for gory details.). Somehow Ivory Boy just isn’t that intuitive, though.

Another alternative – Mr. F1 Help. A good friend of mine came up with that name back in the ‘90’s and I tried coining it for my consulting business at the time, but perhaps it’s a bit too formal. J

So – “The Help Guy”. For the last 8 years that I’ve been working at Microsoft, I’ve worked a lot with Visual Studio Industry Partners (VSIPs) and their need to integrate their Help content with the various versions of Visual Studio that we’ve been shipping since around 2000. To many of them I’ve become “the Help guy.” Also, for many teams in Microsoft who have tried to work with that Help system (Microsoft Help 2.x) I’ve become the go-to guy for getting answers.

Even before working at Microsoft though, I’ve always been passionate about “helping” people with Help related conundrums. I was even a Microsoft Help MVP for several years, and oversee the current Help MVPs now. I just can’t help myself!

So there you have it.

Why here?

I’ve recently moved into a more intentional Partner Engagement type of role with Visual Studio 2010’s shipping-any-day-now new Help system – affectionately dubbed Microsoft Help Viewer 1.0. The meat and potatoes of my job is to ensure that all our Visual Studio partners are successful in migrating to the new Help system (and format), as well as to ensure that their needs and requirements are understood and represented to our team (LEX – Library Experience). Our team essentially owns the MSDN Library as well as the new Help Viewer, so what better place than http://blogs.msdn.com?

A big part of this is making information readily available for our partners. One of the aims of this blog will be to post best-practice types of solutions, workarounds (where necessary), and to document odd bits that have not made it into formal documentation yet.

Why now?

Lots of reasons spring to mind for me. #1 being that my management would like me to. J However, I’ve been thinking about doing something like this for quite a while. The primary thing that’s been missing for me till now has been the right combination of whatever my current job responsibilities were, the team I was on, and the role I could play in the future of a Help system. Right now feels like the right job, the right team and the right time with the right Help system.

My primary aim with this blog is to make information available on this new Microsoft Help Viewer 1.0 platform, especially as it relates to Visual Studio 2010 Help integration. This is critical as it is an entirely new system and way of doing Help. There are and will be growing pains. This is a 1.0 product.

I have a secondary aim though as well – to provide a locus for entertaining, discussing, and opining on any issues pertaining to Help technologies past, present and future. Hopefully, this will be more than just my meandering thoughts… I’d love for this blog to become a place where great ideas for the next broadly public Microsoft Help system are published (by you gentle readers, and me) and come to fruition. To that end, I welcome suggestions on topics you would like to see addressed.

What next?

I will be posting some updates on the status of Help Viewer 1.0 in recent VS 2010 builds, Known Issues, etc. Those types of updates will come pretty regularly at least from here through VS 2010 RTM. However, I hope to continue those types of updates past RTM as well.

As new issues may surface and workarounds become available I will be posting on these as well.

Now what?!

Nothing – just checking if you got this far. ;)

The Help Guy

Installing Content From Downloaded Help Viewer 2.0 cabs

Installing Content From Downloaded Help Viewer 2.0 cabs

Hook Up Visual Studio 11 Developer Preview and Visual Studio Express for Windows Developer Preview to Visual Studio 11 Developer Preview content on MSDN

Help "charm" in Windows 8 Metro apps

Help Viewer 2.0 + Visual Studio 11/Windows 8 Developer Preview

VS 2010 SP1 Beta now available - including new client Help Viewer!

Help Viewer 1.1 Preview Video

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

Help State of the Union (October 2010)

What is Microsoft’s guidance regarding:

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

Fixed Help SDK download now available

Help Viewer 1.0 SDK now available!

Help-related resource pages

Help MVP site

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

The Helpware Group (Rob Chandler)

indoition.com (Marc Achtelig)

EC Software's Help & Manual now supporting Sandcastle

Re-post: Helixoft VSDocman adds support for VS 2010 Help

Sandcastle with MSHC support has been released!

Have you heard about the Preview of MSDN Online Updates?

Updating multiple VS 2010 installations' Help content with a single download

Clever workaround for getting dynamically inserted javascript or stylesheets to work in Help Viewer 1.0

Partner Content Discoverability Options in Visual Studio 2010, Part II: Shortcuts

Partner Content Discoverability Options in Visual Studio 2010, Part I: Context Sensitive Help (F1)

Some updates

Help Authoring Tool (HAT) support for Help Viewer 1.0

What are we trying to accomplish with code signing content?

So how do we prevent this sort of thing – even though the TechNet issue is a web specific example. Here are some of the constraints:

· Even with Admin privileges, Admins don’t always understand the implications of what they are installing, so we still wish to provide notification that the action they are about to take is potentially unsafe.

· With Self-branded content, there's higher risk of script being executed that is potentially unsafe – this, for us implies an even higher risk that we’ll need to protect the user against.

· With Help Viewer 1.0 we are ultimately aiming at a broader user base than just Visual Studio users. We would like to become a replacement for both WinHelp and HTML Help 1.x.

If you look at how security is managed for WinHelp today, its primary attack surface is around its macro capabilities. This is why in Vista and Win7, macros are completely disabled by default. You have to be an Admin to update the registry with some reg keys in order to re-enable these features.

Additionally, with HTML Help 1.x, check out this list on Microsoft Help MVP Rob Chandler’s site:

http://helpware.net/FAR/far_faq.htm#SecurityUpdates

For better or worse, there’s a whole lot of security restrictions on help files now. The difference you may argue is that these are generally mitigated when a user installs a .chm via a setup program.

The primary difference we have with Help Viewer 1.0 however is that a user can install content from media *or* the cloud, as well as updating from the cloud. Currently, this is mostly for Microsoft content, but we are not architecting to limit it to MS only content.

· We ideally wish for a secure mechanism for installing and updating content regardless of the source location.

· We need a mechanism that as a starting point helps guarantee against unsafe script being executed unintentionally, or at least with full knowledge that you’re opening yourself up for that.

How would you provide strong security given these constraints?

Working with signed .cab files

Known Issues

Which IVsHelp Interfaces are supported in Visual Studio 2010?

Welcome!

The primary difference we have with Help Viewer 1.0 however is that a user can install content from media or the cloud, as well as updating from the cloud. Currently, this is mostly for Microsoft content, but we are not architecting to limit it to MS only content.