195 lines
7.7 KiB
Plaintext
195 lines
7.7 KiB
Plaintext
See new features at the bottom
|
|
-----------------------------------------------------------------------------
|
|
To: Mark Walsen, Microsoft Corporation
|
|
From: Mike Orr, Windows Laboratories
|
|
Date: 1 October 1993
|
|
|
|
Re: 16-bit Contents Browser Delivery
|
|
|
|
|
|
|
|
This is to accompany my delivery today of the completed 16-bit Contents
|
|
Browser -- it amounts to a brief set of release notes for the delivered
|
|
programs. Because the 16-bit implementation has been generalized in several
|
|
ways as compared to the previous 32-bit version, this information is
|
|
necessary for anyone testing the delivery or building the components into
|
|
a Microsoft product.
|
|
|
|
The 16-bit browser consists of the following components:
|
|
|
|
HDXCVT.EXE This is a character-based DOS application that converts
|
|
a .GBD file into the .HDX file required by the Help
|
|
Browser.
|
|
|
|
HDXDLL.DLL This Win16 DLL implements the HelpIndex custom control
|
|
class required by the browser application. It has been
|
|
tested as an installable library with the version of
|
|
Dialog Editor that shipped with the 16-bit Windows
|
|
SDK.
|
|
|
|
CONTENTS.EXE This is a Win16 application which offers a HelpIndex-based
|
|
user interface for browsing a help index (.HDX) file and
|
|
launching the associated help topics in WinHelp. The
|
|
32-bit original of this program underlies the Books Online
|
|
component of MSVC/NT.
|
|
|
|
|
|
|
|
PERFORMANCE CONSIDERATIONS. The 16-bit Windows environment makes performance
|
|
a much more significant concern than in the 32-bit implementation. Although
|
|
the 16-bit browser, like the 32-bit version, uses the LZOpenFile() family of
|
|
functions to manipulate the help index, the performance with a file that is
|
|
actually compressed is very severely impaired -- the browser is unusable with
|
|
the compressed version of the BOOKS.HDX file (ca. 1.4MB) I've been testing
|
|
with.
|
|
|
|
Performance concerns have also motivated some techniques that impose capacity
|
|
limits on the 16-bit browser (specifically, the limits come from data
|
|
structures used to cache the index file and from the use of a non-virtual
|
|
listbox). As delivered, the 16-bit browser is limited to:
|
|
|
|
32,500 index entries
|
|
|
|
16 levels of nesting
|
|
|
|
8192 expanded outline items
|
|
|
|
|
|
|
|
HelpIndex CONTROL CLASS USAGE. The HelpIndex control class is a custom
|
|
control class conforming to the Windows 3.1 Dialog Editor's custom control
|
|
interface. It supports a single style, "HS_LINES", which specifies that
|
|
vertical connecting lines should be drawn between siblings in the help
|
|
topic outline structure, and forwards WM_VKEYTOITEM messages to its parent
|
|
window.
|
|
|
|
Once created, a HelpIndex must be enabled by setting its window text in
|
|
a prescribed way, for example, by specifying a text string in a resource
|
|
script or by calling SetWindowText() or SetDlgItemText(). The string
|
|
passed as window text must be of the form "<profilename>|<helpfilename>";
|
|
for example "msvc.ini|vcxxbks1.hlp".
|
|
|
|
This HelpIndex interface requires no action when the control is created by
|
|
the CONTENTS.EXE application.
|
|
|
|
|
|
|
|
CONTENTS.EXE APPLICATION USAGE. The browser application can/must be
|
|
configured using the command line and/or profile settings. In the field,
|
|
Setup would normally be responsible for creating profile settings and
|
|
Program Manager icons that interact properly, but initial internal users
|
|
will need to be careful to get them right by hand.
|
|
|
|
The CONTENTS.EXE command line supplies -- explicitly or by default -- two
|
|
unqualified (no path) filenames: a default help file name, and a profile
|
|
name. The defaults are "vcxxbks1.hlp" and "viewer.ini" for compatibility
|
|
with MSVC/NT Books Online; normally it's necessary to override them. In
|
|
addition to providing the name of the default help file, the first
|
|
argument's basename supplies the section name CONTENTS will use in the
|
|
specified profile. Here are three example command lines and the profile
|
|
sections they would each cause the browser to use:
|
|
|
|
Command line - CONTENTS.EXE
|
|
Profile sect - [VCXXBKS1] in VIEWER.INI
|
|
|
|
Command line - CONTENTS.EXE TEST.HLP
|
|
Profile sect - [TEST] in VIEWER.INI
|
|
|
|
Command line - CONTENTS.EXE TEST.HLP MSAPPS.INI
|
|
Profile sect - [TEST] in MSAPPS.INI
|
|
|
|
A number of other configurable strings control the browser's behavior.
|
|
These strings are identified by names; in most cases, there is a default
|
|
value specified by a string resource, as well as the possibility to
|
|
override the default by using the string name as a keyword in the profile
|
|
section specified by the command line.
|
|
|
|
In addition to the strings that can be specified on the command line,
|
|
the browser recognizes the following configuration strings:
|
|
|
|
Package Name
|
|
Default: MSVC
|
|
Overridable in profile: YES
|
|
Use: The browser stores app preferences (currently just the font)
|
|
in <Package Name>.ini.
|
|
|
|
Contents Viewer App Name
|
|
Default: CONTENTS
|
|
Overridable in profile: YES
|
|
Use: The app preferences section in <Package Name>.ini is
|
|
[<Contents Viewer App Name>]. (This is not the configuration
|
|
profile section and need not be touched by Setup or the user.)
|
|
|
|
Contents Viewer Version
|
|
Default: (none)
|
|
Overridable in profile: NO
|
|
Use: Printed in the user interface.
|
|
|
|
Contents Viewer Helpfile
|
|
Default: (none)
|
|
Overridable in profile: MANDATORY in profile
|
|
Use: Fully qualified path-and-file spec for the browser's own
|
|
help file; e. g., the CONTENTS.HLP in this delivery.
|
|
|
|
Contents Viewer Help Title
|
|
Default: "Books Online Help"
|
|
Overridable in profile: YES
|
|
Use: Becomes caption of the browser application help window.
|
|
|
|
Title
|
|
Default: "Visual C++ Books"
|
|
Overridable in profile: YES
|
|
Use: Becomes the caption of the WinHelp windows launched by the
|
|
browser for the default help file.
|
|
|
|
Title 2
|
|
Default: "Win32 SDK References"
|
|
Overridable in profile: YES
|
|
Use: Becomes the caption of WinHelp windows launched by the browser
|
|
for a secondary help file.
|
|
|
|
Path
|
|
Default: (none)
|
|
Overridable in profile: MANDATORY in profile
|
|
Use: Specifies the directory the browser is to search for the help
|
|
contents file and for helpfiles referenced by unqualified name
|
|
in the contents file.
|
|
|
|
Contents File
|
|
Default: BOOKS.HDX
|
|
Overridable in profile: YES
|
|
Use: Specifies the help contents file (HDXCVT output) containing
|
|
the help topic outline to be browsed.
|
|
|
|
When the browser uses a contents file that contains references to help
|
|
file(s) other than the default file, it searches the current profile for
|
|
sections named after the basenames of these files; e. g., [VCXXBKS2] if
|
|
there are references to vcxxbks2.hlp. These sections must be present and
|
|
each such section must provide a value for the Path keyword (even if the
|
|
path for a secondary help file is the same as for the default help file).
|
|
Other keywords are ignored in these sections.
|
|
|
|
That's it; good luck!
|
|
|
|
-----------------------------------------------------------------------------
|
|
10/20/93 [chauv] new features for Contents version 1.01 includes
|
|
|
|
1) Command line usage: Contents [helpfile] [profile] [expandlevel]
|
|
|
|
where [helpfile] = name of helpfile (i.e. Contents.hlp)
|
|
[profile] = name of profile file (i.e. Contents.ini)
|
|
[expandlevel] = number indicating which level Contents should
|
|
expand to after it's up. Lowest level is 2
|
|
|
|
example: Contents vc.hlp vc.ini 3
|
|
|
|
2) User can switch help/index file on the fly. This means that if Contents
|
|
is already running, the next command execution of Contents will automatically
|
|
updates Contents to the new index file.
|
|
|
|
example: Contents file1.hlp file1.ini ; run Contents the first time
|
|
Contents file2.hlp file2.ini ; Contents will be updated with file2
|
|
|
|
3) Single source tree buildable to 16-bit and 32-bit versions of Contents.
|
|
See build.txt for build detail.
|