ADOC Conference Notes

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/

1. Microsoft Help 2.0

Rob CHandler

Varian Australia

ADOC Conference 2001

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

2. The Evolution of Help

• •Prehistoric: QuickHelp
• •Ancient: WinHelp
• •Renaissance: WinHelp 95/4.0
• •Industrial revolution: HTML Help 1.x

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

3. Help 2.001?

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

4. Help 2.0 Concept Car

• •This is a preview
• •Some design points will change by the time it hits the showroom
• •The model year for production is 2002

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.

5. Help 2.0 Vision

• •Improved user experience
• •Improved author experience
• •Improved developer experience
• •Easy migration from HTML Help 1.x

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.

6. Better User Experience

•Improved UI behavior

• –One set of features
• –Consistency across Help files
• –Fewer author-controlled settings for UI

•Improved navigation

• –Easy reduction of document scope
• –Filtering based on topic attributes
• –Filtering applies to all navigation

•Improved integration with applications

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.

7. Better Author Experience

• •HTML for content, XML for metadata
  • - No Object tags needed
• •Standard URLs
• •Hierarchical collections
• •Round-trip decompile
• •Topic Attributes and attribute-based filters
• •Virtual Topics
• •All Help features available to all authors

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]

8. Better Developer Experience

•Programmatic access to all Help data

• –Table of contents
• –Keyword indexes
• –Full-text search
• –Topic attributes
• –Filters
• –Content registration

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

9. Architecture Overview

• •Data services
• •UI components
• •Viewer

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

10. HTML Help 1.x/Help 2.0 Table of Equivalence

11. The Collection File

• •.HxC XML file replaces .HPJ file
• •Specifies which files make up the collection
• •Specifies properties of the collection

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

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

12. Table of Contents

• •.HxT XML file specifies TOC hierarchy
• •Can link to any URL
• •Can include other TOCs
• •One TOC format, one set of features
• - –No binary vs. “sitemap” differences

.HxT replaces .HHC

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

13. Keyword Indexes

• •Indexes declared in .HxK files
• •Author-defined indexes
• - You can still use “A” and “K”
• - Add samples index, API index, F1 index, etc.
• •Keyword markup in topics
• - <MSHelp:Keyword Index=“A” Term=“foo”/>
• •Keywords can also be defined in .HxK file
• •One index format, one set of features
• - No binary vs. “sitemap” differences

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

14. Keyword Links

• •Logical extension of A-links and K-links
• •Links to keywords in any index
• •Links are now XML elements rather than object tags:
• <MSHelp:link keywords=“My keyword”>
• Click Here</MSHelp:link>
• •Result list can be shown as a menu or expanded in-place as a table

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

15. Keyword Tables

• •Like links, but expanded in-place when the page loads
• •Can be displayed as a table or as a list of links
  • <MSHelp:ktable keywords=“My keyword”>

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.

16. Topic Attributes

• •Attributes are properties of topics
• •Name-value pairs
• •Enable filtering
• •XML markup in topics
  • <MSHelp:Attr Name="role" Value="manager"/>

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.

17. Attribute-based Filters

• •Filters are Boolean expressions using attribute name-value pairs
• (Animal=Ape OR Vegetable=Eggplant) AND TopicType=Reference
• •Filters reduce the effective size of the content
• •Filters apply to all navigation
• •You control the filter selection/creation UI

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.

18. Topic Titles

• •Titles shown in TOC and result lists can be specified in the topic
• •For TOC:
• - –TOC entry
• - –<MSHelp:TOCTitle>
• - –<MSHelp:RLTitle>
• - –<TITLE>
• •For Index/Search result lists:
• - –<MSHelp:RLTitle>
• - –<TITLE>

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

19. The Collection File (Revisited)

• •Unified collections model for Help 2.0
• •A single file (.HxS) is the simplest collection
  • - –.HxC is both project file and collection file
• •Multiple file collections defined by "top-level" HxC
• •Hierarchical collection mechanism allows collections to "plug in" to other collections

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

20. Help URLs

• •ms-help://namespace/file/path/file.htm
• - –"ms-help:" is the protocol for Help URLs
• - –"namespace" is the name of your collection
• - –"id" is a name for a compiled Help file
• - –"path" is the path within the compiled file

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

21. Namespaces

• •Are location-independent
• •Define collections
• •Are registered (usually at setup time)

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

22. Relative Links

• •ms-help:file.htm
• - Relative to current (containing) page
• •ms-help:/../common/startup.js
• - "/.." refers to the current collection
• - "/../common" refers to a "sibling" .HxS file registered as "common" in the current collection

Single and Multi-help file collection have path

ms-help://NameSpace/FileID/Path/File.htm

23. Virtual Topics

• •Abstraction of Help "topic" from HTML file
• •A virtual topic is identified by a URL
• •Every topic has properties
• - –Searchable text
• - –Keywords
• - –Attributes
• - –Titles

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

24. Virtual Topics Defined in .HxV

• •Authors can specify any URL as target of links to topic
• - –Can be any file: GIF, JPG, PDF, DOC, etc.
• - –May be compiled in to Help file
• - –May be on Web
• •Build-time HTML can be used for
• - –Keywords and attributes
• - –TOC title and Results List title
• - –Full-text Search parsing

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.

25. In-topic Virtual Topics

• •Authors can specify parts of an HTML file to be in a virtual topic
• •URL of virtual topic uses standard # form
• - ms-help://ms.msdn/sample/step1.htm#vb

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.

26. Compiler

• •Supports Unicode HTML/XML content
• - –Both UTF-8 and 16-bit Unicode
• •Supports full decompilation

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

27. Standard Viewer

• •More standard browser-like experience
• - –Hide/show replaced by Internet Explorer “Explorer Bar” model
• •Users (rather than authors) will control viewer properties
• - –Single- vs. double-click in TOC
• - –Auto-sync
• •Still "under wraps"

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.

28. Authoring

• •Microsoft Help 2.0 Workshop package hosted in Visual Studio.NET shell
• - –Build-centric
• - –Manage files and project options
• - –Won't require Visual Studio.NET
• * But will work with in it if present
• •WYSIWYG TOC authoring
• •No special support for Help 2.0 XML topic markup
• •Best authoring experience will be 3rd-party tools

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.

29. Side-by-side Compatibility

• •Help 2.0 and HTML Help 1.x are completely independent and will operate side-by-side
• •Source changes are evolutionary
• •Output file changes are revolutionary
• •Conversion tool is provided
• - –Converts compiled .chms or Help project source
• - –Output is Help 2.0 source files
• - –Not a production tool—recommended for one-time use
• •New COM API for Help 2.0
• - –HtmlHelp API still works for HTML Help 1.x

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.

30. Help 2.0 Tools from Microsoft

•Available when Help 2.0 is released:

• –Help 2.0 compiler/decompiler
• –HH 1.x converter
• –Microsoft Help 2.0 Workshop
• –Index pre-merge tool
• –Command-line content registration tool

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.

31. Help 2.0 Support

• Doc-to-Help – WexTech Systems (www.wextech.com)
• True Help – ComponentOne (www.componentone.com)
• HyperText Studio – OlsonSoft (www.olsonsoft.com)
• ForeHelp – ForeFront (www.ff.com)
• HelpKit – DevComponents.com (www.devcomponents.com)
• HDK – Virtual Media Technology (www.vmtech.com)
• FAR – The HelpWare Group (www.helpware.net) ** That's Mine **
  • KeyHelp – Keyworks Software (www.keyworks.net)
  • DotCHM – Auric Visions Ltd. (www.auricvisions.com)
  • HelpBreeze – SolutionSoft (www.solutionsoft.com)
  • RoboHelp – eHelp Corporation (www.ehelp.com)
  • More to come…

32. MS Help MVPS

Find them at: http://msdn2.microsoft.com/en-us/library/ms670169.aspx

• Josef Becker, Becker & Poettgen Software GmbH
• Scott Boggan, HelpCraft
• Robert Chandler, Varian
• Dana Cline, CompuServe HYPERTEXT forum sysop
• Jeff Hall, Eon Solutions
• Yuko Ishida, KeiYu HelpLab
• David Liske, Delmar Computing Services
• Cheryl Lockett Zubak, WorkWrite
• Paul Neshamkin, The Paul Neshamkin Group
• Paul O'Rear, Helpful Solutions/South Mountain Software
• M.J. Plaster, WWWinnovations

Find them on these discussion lists

• http://groups.yahoo.com/group/MSHelp2
• http://groups.yahoo.com/group/HATT
• news://msnews.microsoft.com/microsoft.public.helpauthoring

33. Schedule

• •Help 2.0 Preview March 2001 (now)
• •Help 2.0 Runtime will ship with Microsoft Office Developer and Visual Studio.NET
• •Help 2.0 beta summer 2001
• •Visual Studio.NET will RTM in 2001
• •Help 2.0 public release to follow Visual Studio.NET release

RTM - Released To Manufacturing

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

34. Call To Action

• •Investigate Help 2.0
• - –Conference CD
• - –Join MSHelp2 mail list / discussion group
• (http://groups.yahoo.com/group/MSHelp2)

35. Q&A

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