windows-nt-4.0/private/sdktools/vctools/contents

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.