Session:  Microsoft Help 2.0 Unveiled - Wed 11:15am-12:30pm
    Presenter: Rob Chandler, MS Help MVP
   ADOC Web Site: http://conference.hyperwrite.com.au/

Shane McRoberts is the head Program Manager for the Microsoft help development team. This presentation was given by Shane at the US WinWriters conference a few weeks ago. In November 2000, MVPs & ISVs attended an intensive 2 day lecture at MS Redmond on MS Help 2.0. Today I just want to give you an introduction to the world of MS Help 2.0.

I'm Rob Chandler from Varian Australia. 

BTW: Shane chose the background because of a crack I made about H20 being the water of life :-)

• 1988 QuickHelp shipped for MS DOS. 
  Did anyone author in QuickHelp? Does anyone remember Quick Help?
  The MS guys couldn't even find a copy of it.
• 1990 WinHelp was shipped with Windows 3.0
  WinHelp is over 10 years old now; practically forever in PC time. What other file format is still supported after that many years.
• 1995 WinHelp 4.0 was shipped with Win95/NT3.5
  Windows 95 Help (WinHelp 4) was a major advancement for WinHelp. It looked different, but still kept many of the features of previous generations.
• 1997 HTML Help 1.0 shipped with Internet Explorer 4.
  HTML Help was a major revolution in the way we work and in the way Help works.
  How many people are now using HTML Help now?

So what's next?

Thus Spoke Zarathustra -(2001 Black Monolith?)

Help 2.0 is an evolutionary step for authors, but it may cause a revolutionary improvement in Help (we hope it does).

This is just a preview; the software on the CD is not even a beta—not all features are there.

Nothing you will see today is final

But remember that cars are sometimes released before the calendar year begins.

Basically, we set out to make Help better for everyone, but most importantly we wanted to make it better for your customers. 

To accomplish this, we new we had to make Help easier to author, with an orthogonal feature set, and easier to integrate with applications.

We also new that we had to have an evolutionary approach to authoring—the transition could not be revolutionary, as it was to go from WinHelp to HTML Help 1.x.

Better user experience – Evolutionary
Users who have used currently available Help systems and browsers will immediately understand how to use Help 2.0.

Improved UI behavior:

One set of features - Collections & HTML Help now one -> Help 2 Collections
Consistency across Help files. 
     Some CHMs were authored to Sync, TOCs to single/double-click, TOC & Index Binary/Non-Binary
So fewer authoring-controlled settings for the UI

Improved Navigation:

Easier navigation of large document sets

Easy reduction of document scope

The problem of scope reduction was especially evident when pressing F1 in VS 6.0. 
When you hit F1 in VC (for instance) you'd get a list of hits from areas you didn't care about, like VFP, VJ, VB, etc.

Dynamic filtering based on topic attributes

Specifically topic attributes, not based on navigation item attributes

Filtering applies to all navigation

Not just TOC
Index doesn’t have grayed out elements

Custom navigators possible

Custom navigators can be written that access the Help 2.0 data services, so third parties can make their own TOC controls, for example.
This doesn't mean that you can replace the TOC in the standard viewer with a different TOC—that would break user expectations. 
But you can make your own viewer or your own navigator integrated with your application.

Better Author Experience – Evolutionary

Source is HTML. Using this open standard lets you take advantage of a huge number of tools, books, etc.

Source files are fundamentally the same as in HTML Help 1.x—HTML with metadata markup, but now rather than Object tags for metadata, we use XML (remember that XML didn't exist when HTML Help 1.x was designed)

Help 2.0 URLs now follow standard URL rules (no double colon, for instance)

Hierarchical collections (sets of Help files) can now be built and accessed using standard URL mechanisms.

Loss-less decompile is now possible. This is particularly useful if you are localizing your content—you can hand the localizers the completed Help file, they can decompile it, localize it, and recompile it without you having to distribute source.

Topic attributes and attribute-based filters replace the HTML Help 1.x "featurette" called information types.

Virtual topics allow you to apply navigation (including keywords and search) to any type of file, not just HTML. 

And finally, we're not holding anything back. All Help 2.0 features are available to all authors (and developers). We're being completely open—no proprietary MSDN features. [Disclaimer: this doesn't mean we'll release all software built on top of Help 2.0]

Better developer experience - Revolutionary
Data Services for Help

Help files are specialized, indexed databases of searchable, browsable content

Great UI customizability and integration

Embedding is easy; new UI is easy

New COM-based API for easy integration with VB and other languages

Data services

COM components
Provide programmatic access to hierarchies, indexes, etc.
Accessible from VC, VB, script

UI components 

Provide standard Help UI behavior

Viewer

HelpHost API accessible by both applications and content pages

Simply an XML replacement for the .INI-style .HPJ file

Can reference a .HxF to list the files to include in the collection

.HxT replaces .HHC

Custom icons are supported and the bitmap can be compiled into the file (HH 1.x bug is fixed).

XML .HxK replaces .HHK

Like WinHelp/HTML Help 1.x
A (associative) and K (visible keyword) indexes
MSDN have F Index used for F1 help.

Keyword markup is now XML island in your HTML topics

Logical extension of a-links and k-links
Help 2.0 supports author-defined indexes

E.g., samples index, API index, F1 index
VS is using K, A, and F
F stands for F1 index; it's where keywords are stored 
that are used just for the DH window and F1 improvement.

Links can reference any index
Links are now XML elements rather than object tags:

<mshelp:link keywords=“My keyword”>Click Here</mshelp:link>
Here’s a more extensive example:
<MSHelp:link 
  keywords="Alink_example"
      color="blue"
  hoverColor="green"
       indexMoniker="!DefaultKeywordIndex"
  navFailPage="/KeywordNotFound.htm"
  TABINDEX=0
>Alink example</MSHelp:link>

Links are implemented as IE Behaviors that use the data services
This effectively means you could implement your own equivalent

Page load will be slightly slowed due to the keyword lookup—just like any other startup script.

Table is sorted by Topic title by default.

Attributes are properties of topics
    Name-value pairs
    XML markup in topics

Attributes must be declared in .HxA file

For those of you with programmer resources…
    Note that since attributes are available programmatically, they can be used for other types of topic selection as well. A great example of this is the Dynamic Help window in Visual Studio.NET, which uses programmatic keyword lookups and attribute comparisons to compute a best match, but which doesn’t use filters at all.

You define the attributes you want to use—there are no predefined ones

Attributes used in filters must be completely enumerated in the HxA file—that is each value must be predefined.

Filters are boolean expressions using attribute name-value pairs
    (DevLang=VC OR Technology=Win32) AND TopicType=Reference

Unlike VS6, index entries that are filtered out don't appear as disabled entries—they don't appear at all.

TOC:
    If no title is specified in a TOC entry, the title from the topic is used. 

    Highest priority is title in TOC entry
    Next is TOCTitle specified in topic
    Next is RLTitle specified in topic
    Next is TITLE specified in topic

Keyword
    Highest priority is RLTitle specified in topic
    Next is TITLE specified in topic.

RLTitle=Result List Title

Unified collections model for Havana
    HTML Help 1.x had two collection models: "Merged CHMs" and MSDN collections
    Merged CHMs was the only publicly documented way

A single file (.HxS) is the simplest collection
    .HxC is both the project file and the collection file

Multi-file collections are also defined by HxC files.

Hierarchical collection mechanism
    Makes it easy to aggregate collections into super-collections

ms-help: replaces mk:@msitstore and ms-its

A namespace is the equivalent of a domain name in http: URLs
A namespace replaces the CHM path in the old HTML Help 1.x URLs

The ID stands for an individual compiled Help file. Typically the ID will be the name of the .HxS file without the extension, but this is not required.

The path is the path *inside* the .HxS file, just as you can use a path after the double-colon in HTML Help 1.x URLs

File.htm is just the filename

Namespaces are a location-independent way to define and reference collections

Typically, namespaces will be the same on every machine regardless of the installation location of the files

Single and Multi-help file collection have path
ms-help://NameSpace/FileID/Path/File.htm

Topics no longer have to be limited to HTML files, and there can be more than one per file.

The unique identifier for a virtual topic (or any topic) is its URL. For some virtual topics, this includes the # and an anchor name.

Every topic, whether virtual or not, has searchable text, keywords, attributes, and titles

Virtual topics are first-class topics. That is, as far as the Help runtime is concerned they are the same in every way as traditional one-per-HTM topics

The .HxV file is used for the declaration of most virtual topics.

The target of a link (TOC, Index, Search) to a virtual topic can be any URL, either local or remote.

In the HxV, the author can specify all the keywords, titles, and search text.

Or, alternatively, the author can specify a file to parse to obtain this information. The file must be in HTML format but does not get compiled into the collection.

In this way, XML can be transformed (at build time) into HTML, then the XML file can be compiled into the collection, and the HTML file discarded after build.

This is the only practical way to support XML (or PDF, etc.) content because otherwise our DTD or schema would clash with yours, and the compiler would have no way to know what parts of your XML file should be parsed for full-text search.

Example:

Imagine you are writing a topic that describes an API function that can be called from either VB or C++. In VB, the appropriate keyword and TOC title for the topic might be Document.Open. But in C++ it would be Document::Open. Further, you have provided filters that allow the reader to select one of these languages (so they don't have to see the other). Because keywords and TOC titles are properties of topics, if a topic is not filtered out, all of its keywords will show up in the index, and all TOC entries that point to it will show up in the TOC. This means that if you don't want C++ programmers to see the VB keywords (and TOC entries), you would have to make a completely separate topic for each language.

Enter in-topic virtual topics. These let you specify the VB keywords for the VB "subtopic" and the C++ keywords for the C++ subtopic. TOC entries can be authored to point to the #vb or #cpp URLs, and they'll all be filtered appropriately even though they point to the same page. This applies to search as well.

You can then go one step further and write script in the page that checks the current URL to see which anchor was navigated to, and then selectively show the appropriate sections of the content.

Support for Unicode (UTF8 and UCS2) HTML/XML content
Enhancements to support authoring tools
    Compiler becomes a COM server
    Errors and warnings reported to client
    Also available as a command-line compiler: HxComp.exe
Supports full decompilation and round-trip recompilation
    As mentioned earlier, this can be very important for localization

We're not saying much about the viewer experience for now. In the Help 2.0 preview, you'll use the Dexplore viewer, which is the one that MSDN will be using. The standard viewer will be simpler to use with no docking windows to confuse novice users.

This is NOT included in the preview release. It will be included in our public beta later this year.

“Microsoft Help Workshop” package hosted in Visual Studio.NET
    Build-centric
    Manage files and project options
    HTML editing in VS editor
TOC authoring
Index authoring postponed
Testing features postponed

We expect the Help Authoring Tool vendors to do a better job than we do on the authoring tool.

Our goals: 
- Make the authoring transition easy
- Avoid breaking existing content

The conversion tool is included in the Preview. This will be the easiest way for you to get started producing Help 2.0 content.

Work on HH 1.x now will pay off when Help 2.0 ships

Continued development of HH1.x content carries forward very well to Help 2.0 - it will continue to work (side-by-side compatibility), can be migrated to Help 2.0 using MS-provided conversion tool, and both formats will be supported by HATs.

Index merge tool is so Help publisher can pre-create combined Search indexes

Plenty of opportunity here for ISVs

You may see HxMerge.exe referred to as HxIndex in the docs.

RTM - Released To Manufacturing

This slide reflects our current best estimates, but the schedule is subject to change.

• Q. So still require IE3 or greater. 
  A. No the XML requirement means that IE5 is now minimal requirement.
• Q. Does H2 now work on the web.
  A. No. That is not yet. Help.NET is an issue being discussed at the moment.
• Q. Can we now encrypt and protect help
  A. No. This issue is still on the possible to-do list. The immediate work has been rewriting Help.