The first complete guide to state-of-the-art online Help with HTML Help, DHTML, and CSS!
The best way to create Help systems for Windows software is with Microsoft's advanced HTML Help system-and the best way to use HTML Help is to leverage the power of DHTML and Cascading Style Sheets at the same time. Building Enhanced HTML Help with DHTML and CSS shows you how to use all three technologies together. Written by one of the first developers to create an industrial-strength HTML Help system, it delivers proven methodologies and instructions for building world-class help systems with both Web technologies and traditional publishing strategies. The book's step-by-step coverage includes:
Along the way, Jeannine Klein identifies the most common problems that occur in real-world HTML Help construction-and presents detailed, proven solutions. Whether you're a technical writer, documentation manager, or developer, if you need to deliver the best possible help, Building Enhanced HTML Help with DHTML and CSS is the complete sourcebook you've been looking for.
Click here for a sample chapter for this book: 0130179299.pdf
1. It's Not Just Help, It's HTML Help Basic ideas & their corollaries.
The corollaries. A note on terminology. The enhanced proposition. A complete process. Basic HTML Help+DHTML+CSS = Enhanced HTML Help. Who should read this book. What you can learn from this book. Limitations. Chapter overviews.
Notes on file types & extensions. Planning the system design. Traditional online help decisions. Audience/needs analysis. Organization: reference vs task. Navigation model. Tools. HTML aspects. Compiled or not? Graphical look and feel (CSS). Action & interactivity (DHTML). Directory structure. Crafting reusable elements & templates. Create the reusable elements (graphics, CSS, and DHTML). The graphics. The style sheets (CSS). The dynamic HTML (DHTML). Assemble the templates. Write the individual pages. Creating the HTML Help project. Project definition. Create the project & add its topic files. Specify parameters. Window definition: size & styles. Building the navigation system. Contents. Index. Compiling & testing the project. Merging modular projects. Efficiency. Merging requirements. Setup options. Ensuring compatibility & binary index options. Specifying merge files. Window definitions. Merging references. Preparing merged tables of contents. Using proper cross-file link syntax.
HTML Help Editor. HTML Help Image Editor. Designing the templates. Identifying the necessary templates types. Creating reusable elements. Fashioning the graphic elements. Assembling a screen capture library. Writing reusable text. Creating the templates. What it looks like. How it's done. Recipes for common HTML. Basic syntax. Document setup elements. HTML. HEAD. Title. Body. Local formatting tags. Bold & Italic. Code. Font. Center. Break. No Break. Body element tags. Headings. Paragraphs. Images. Anchors. Lists. Bulleted (unordered) lists. Numbered (ordered) lists. Numbered list with bullet sub-items. Definition list. Tables. Table. Table row. Table header/table data. Writing the HTML topic pages. How HTML works with HTML Help-& how it doesn't. Titling tricks. Author beware. Linkages. Background basics. Links within a single CHM. Links between CHMs. External links from the CHM. External links to the CHM.
How to do it. Browser-dependence. Types of cascading style sheets. Linked style sheets. Embedded style sheets. Inline style sheets. Creating the style sheet. Style definition: the basics. The rules of inheritance. Selectors. Class selectors. Pseudo-classes. Contextual selectors. Anatomy of a value. Color values. CSS color names. RGB color values. Hexadecimal values. Browser-safe colors. Spatial values. Absolute: length values. Relative: percentage values. Keywords. Crucial properties for Help. Font properties. font-family. font-size. font-style and font-weight. font-variant. font (shorthand property for font properties). Text & typography properties. text-decoration. vertical-align. text-align. line-height. text-indent. Color & background properties. color. background-color. background-image. background (shorthand property for backgrounds). Box properties (margin, padding, borders). Variants & shorthand versions. padding-top (-right, -left, -bottom), padding. border-top-style (-right-, -left-, -bottom-), border-style. border-top-color (-right-, -left-, -bottom-), border-color. border-top-width (-right-, -left-, -bottom-), border-width. border-top (-right, -left, -bottom), border. margin-top (-right, -left, -bottom), margin. Classification (listing) properties. list-style-type. list-style-image. list-style-position. list-style. Printing properties. page-break-before (-after, -inside). How CSS works with HTML Help-& how it doesn't. Adding the style sheet to the project. Areas of enhancement: fonts. Arenas of conflict: spacing, inheritance, & split files.
Building a DHTML script. How to do it. Linking to an external script file. Embedding a script file. Adding the external script file to the project. Where to author. Basic script syntax tips. Basic JavaScript terminology. Objects. Properties. Dot notation. Naming objects. Referencing properties. Using "this" as a reference. Variables. Events & event handlers. Functions. Methods. Crucial DHTML elements for HTML Help. Common objects & their properties. window. document. image . anchor < A>. style. all. Date. Common events & event handlers. onClick. onMouseOver. onMouseOut. onLoad. onUnload. CSS properties for DHTML. Index. visibility & display. DHTML recipes for HTML Help. Quick & easy tool tip. Change text color on mouseover. Show/hide text. Status bar explanation of an image map. Open secondary window. Image rollover. Alert message using input from a prompt. How DHTML works with HTML Help-& how it doesn't. Areas of enhancement. Single browser/limited versions. Focused examples. Arenas of conflict. Explicitly adding files to avoid lost paths. Jumping to other topics. Linking to secondary windows. Taking care with positioning elements. Splitting files.
The trivial New Project Wizard. Directory structure. File & directory conventions. Using the New Project Wizard. Refining the project. Adding topic & navigation files. To add files to an HTML Help project (in the Workshop):. To add files to an HTML Help project (in Notepad):. Setting project options. Those surreptitious essentials. Dealing with window types. Creating window types. Advanced info: Understanding the project file's window type specs. Fun with hex. Pulling it all together. Save early, save often and close the Workshop. The moment of truth: compiling. Compiling from the command line. Previewing & troubleshooting the results.
The Workshop's graphical interface. Understanding how the Workshop tabs work. Creating a TOC on the Contents tab. Automatic generation. Understanding how the automatic TOC works. Creating an automatic TOC. Editing automatic TOCs. Manual TOC creation. Basic TOC settings. Setting up the TOC in the Workshop. Setting up the TOC manually. Graphic considerations. Changing the TOC font. Available styles. Binary or not? Perils ahead. The unfixables. TOC workarounds.
The HTML Help author's experience. Benefits. Merging requirements. Meeting the requirements efficiently. Procedures for merging. External procedures. Main module settings. Global settings. Perils ahead. General troubleshooting tips. Troubleshooting the TOC.
How it works. Binary vs sitemap Index. Location, location, location: Where to put keywords. Setting up an Index. To create a binary Index. To create an Index file (sitemap or binary Index). Troubleshooting Index settings. Cross-references. Available options. To create cross-referencing links. Full-text search. How it works. Search vs Index. Setting up full-text search. To enable full-text search. To create a stop list. Shortcuts. To create a shortcut in a topic file.
HHUPD.EXE: The standard approach. Getting the version right. Running HHUPD.EXE. Internet Explorer 5: an alternate approach. Looking ahead: Windows. 2000. Windows 2000. Index.
"Users don't use help."
"People don't want to read long documents online."
How often have you heard these statements? It often seems that the two abiding truths in the world of the Help author are "no one reads manuals" and "no one uses help." For the online content provider, one of the central truisms seems to be "no one wants to read on a computer."
But who is this mythical "no one"? Does such a person really exist? The evidence suggests otherwise.
On the one hand, a significant proportion of the World Wide Web explosion centers on the search for content, for information, even for complete documents and electronic books. One extremely popular author's online release of his latest mystery caused a virtual traffic jam online; medical sites are bombarded by requests for downloads of complex medical texts; ebook initiatives are springing up everywhere;. and the most popular online bookstores have added electronic delivery options.
At the same time, online Help is growing in unprecedented ways. User assistance is being added to everything from stock portfolios to online museums, whether distributed over the Web or on CDs-Certainly "someone" is reading online and using the new generations of Help. And the most exciting possibilities of all arise from the merger of the two worlds, combining the best of HTML with the best of online Helpquite possibly, in a new format from Microsoft® that is called compiled HTML Help.
HTML Help goes miles beyond the boring yellow pages with tiny type that have become the de facto Windows help standard. The "HTML" components possess the capability to be both dynamic and interactive, presenting a style as strong as the content. Web technologies enhance the system with cascading style sheets (CSS) for control over layout, and with dynamic HTML (DHTML) that allows the author to customize contentand design presentations that literally move the information to meet theuser's needs. These enhancements are not merely aesthetic tricks, but legitimate tools that allow the writer to appeal to the needs of all types oflearners and all sorts of situations. These needs are also addressed by thestrong architectural and navigational components that the "Help" part ofthe equation brings to the table. Drawing on the Windows help tradition,HTML Help supplies built-in tools for creating indexes, full-text search (FTS),and tables of contents that are synchronized to the user's current page.
As its name implies, HTML Help is designed for online Help in the Webera. It is the new standard in Microsoft Windows 98® and 2000® and is evermore commonly used in applications that run on these platforms, includingMicrosoft® Office. While the Office systems are easily identifiable asHTML Help, many other HTML Help systems are less easy to spot. Most ofthe Microsoft Home products push the HTML Help envelope in their formatand approaches. But more surprising (and more difficult to see) arethe third-party tutorials and online books being published with HTML Help.An amazing wealth of content-rich, visually complex works are now beingpublished from the HTML Help platform, including encyclopedias and worksof literatureand the online fanatic's guide to at least one wildly populartelevision show!
And the best part of the HTML Help revolution is that it's not difficult tojoin in. While the full world of HTML, Help, CSS, and DHTML is stunninglywide, you need not master it all to create rich, useful, and attractive HTMLHelp systems. In this book, you can learn everything you need to get startedand successfully produce your own HTML Help system enhanced with Webtechnologies. After that, the only limit is your own imagination.
The basic idea underlying this book is that HTML Help can and should bean enhanced format for online user assistance and information publishing,taking advantage of the best of both HTML and online Help.
HTML Help merges the world of the Web and the world of online userassistance (commonly known as "Help" or "what you get when you pressF1"). Online help has a long history of developing useful content (whetheror not "anyone" reads it). On the other hand, the enormous growth of theWeb in recent years suggests that users prefer and are more comfortablewith the Web model of information gathering than with the traditionalHelp models. HTML Help offers the best of both worlds.
One of the easiest paths to that "best of both worlds" scenarios is throughcompiled HTML Help, which is the method discussed in this book. Ingeneral, HTML Help can mean any system that uses standard HTML pagesto create an online help system; in practice, HTML Help most often refersto Microsoft's version of compiled HTML Help, while other systems arereferred to as HTML-based Help. HTML-based Help systems have theadvantage of running on any computer with any Web browser; however,generic HTML-based Help does not offer any easy way to create a table ofcontents, indexing, or search facilities. In addition, the user must have asmany .htm files as there are pages in the Help system. (Some third-partysystems supply the navigational components, but the multiple filerestriction remains.) Also, Help systems designed to run "in any browser"must deal with an incredible number of variations in the ways that differentbrowsers implement Web technologies such as HTML, DHTML, and CSS.In practice, these variations force authors to create "browser-sniffing" scripts,multiple implementations for multiple platforms, or design only for thelowest common denominator, doing away with tables and frames (not tomention DHTML and CSS).
Microsoft's system, referred to as compiled HTML Help, requires users tohave Internet Explorer® 3.01 or above on their systems, although they need not use it as their default Web browser. The Internet Explorer installation(a standard component on Windows 98 or 2000 machines) allows HTMLHelp to provide built-in contents, index, and searching facilities. It also letsyou use most of the special capabilities available to HTML, CSS, and DHTML.Since HTML Help uses the Internet Explorer engine, it avoids the difficultiesof testing and coding for various browsers. Finally, the compiled versionallows you to distribute only a single file (.chm) for your help system.
One of the strongest lessons learned from the popularity of the WorldWide Web is that style aids substance, that the two are inseparable partners.HTML Help used for user assistance or online publishing must havecontent; but there is no reason why it should not also have style and sizzle.
Writers can use HTML Help's access to Web-publishing features such ascascading style sheets and dynamic HTML to quickly and efficiently addboth style and substance, customizing the content and presentation tothe user's needs. And the Web-based approach of HTML Help opens thefield to people who are not dedicated tech writers and Help authors. As"everyone" becomes familiar with basic HTML, HTML Help will open anew world of online publishing to anyone with basic HTML knowledge.
The full Microsoft system can be referred to either as compiled or compressedHTML Help. The most common term to date is compiled HTMLHelp. However, these systems are not compiled in the strictest sense (thefinal file doesn't run on its own but requires the Internet Explorer engine),but they are compressed (compare the total size of all the included files tothe total size of the final .chm file). Microsoft documents are beginningto refer to these systems as "compressed HTML Help," but most of theMicrosoft Web site and most technical writer conversations use "compiledHTML Help." The term used in this book is "compiled HTML Help."
The information in this book is based on knowledge that I have gained intwo years of creating real-world HTML Help systems for the Hewlett-PackardTMCompany. The first of these systems shipped in 1998, when HTMLHelp was definitely bleeding-edge technology. Many of the lessons I learnedwith that first system are presented as examples in Chapter 2, "So HowDoes It Work," in the hopes that they will keep you from "bleeding" quiteas much as you first enter the wonderful world of HTML Help.
Since its first release in 1998, my original HTML Help system has been repeatedlyenhanced as it lived through a variety of upgrades, spin-offs,repurposings, and external adoptions; the lessons learned fromthese changes provide the real-world testing backing up the theories andtechniques described throughout this book. Over time, the systems have been well received by customers, developers, and other writers. Perhapsthe greatest tribute is the number of fellow Hewlett-Packard writers aroundthe world who have not only adopted my basic system, but have consistentlymade it their own with adjustments and enhancements as new technologiesbecome available and as new minds envision new approaches. Ibelieve that the ability to consistently "grow" an HTML Help system is oneof the truest benefits of this technology.
The presentation of HTML Help in this book suggests a complete processfor creating enhanced HTML Helpa process based on real-worldexperience as well as theoretical exploration and experimentation. Theunderlying concept is that you can most efficiently create HTML Helpas an iterative process whereby you begin with an overview of yourproject, then craft each element as the necessary materials andinformation become available. In other words, create content wheninformation is available; design graphics when stylistic parameters aredetermined; and craft scripts and style sheets as needs become obvious.The key is to create each element in a reusable and revisable form sothat it is always "good enough," but is also always getting better. Thisapproach lets you make the best use of your time by working in a serialfashion on the multiple "threads" involved in HTML Helpan approachnot unlike the "componentization" currently advocated and practicedby many software development teams.
The multiple threads of HTML Help allow you to combine basic Help systemfunctionality with Web capabilities to create enhanced HTML Helpsystems. HTML Help brings with it the rich heritage of Windows help,with navigational and other features not easily available in HTML. Specifically,the Windows help heritage gives HTML Help advantages over standardHTML that include:
From the other side, HTML brings the exciting new world of Web technologies, such as dynamic HTML and cascading style sheets. Specifically, HTML and other Web technologies add the following advantages to the equation:
Finally, in addition to the Windows help and HTML capabilities, HTMLHelp brings its own rich set of functionality, including the following:
All combined, the equation adds up to rich online assistance or ebook publishingthat is, enhanced HTML Help system.
This book is designed for anyone who wants to package a collection ofinformation in a single-file format that incorporates the attributes of HTML,including the sophisticated design and interactivity of cascading style sheetsand dynamic HTML, plus convenient navigational facilities. Although theprimary audience consists of Help authors and documentation specialistsinterested in moving to HTML Help, the book should also prove useful toothers who want to publish writing in a highly functional, self-containedpackage that takes advantage of the explosion of technologies and accessavailable on the World Wide Web.
Overall, no previous knowledge is assumed beyond a general familiaritywith using Windows Help systems and the World Wide Web. Novices toWeb and Help authoring should be able to learn the essentials required tobuild enhanced HTML Help; at the same time, experienced Help and Webauthors should find enough new material to challenge them to enhancetheir existing systems.
On the one hand, this book does not attempt to provide a complete coursein every aspect of HTML Help, DHTML, and CSS; however, it does provideall the information necessary to build a more-than-adequatein fact, anenhancedHTML Help system. Hefty chapters on HTML, DHTML, andCSS each provide a bit of background and an overview of what is possiblewith the technology; detailed descriptions of the tags, attributes, and otherbits of coding employed by each technology; and pre-canned code bitspertinent to HTML Help systems.
On the other hand, this book is designed to provide a substantially completeguide to HTML Helpthe framework that brings all the other aspectstogether. Individual chapters cover specific aspects of HTML Help,including the project file, the table of contents, navigational facilities (indexing,search, etc.), merged projects, and final distribution to your audience.
All work in this bookcan be done withinthe HTML HelpWorkshop (freelydownloadable atmsdn.microsoft.com/library/tools/htmlhelp/) or inWindows Notepad.No other tools areneeded.
This book takes a "purist" approach to building HTML Help, avoiding dependenceon third-party tools. Although individual chapters discuss (andoccasionally recommend) specific tools for building HTML Help, HTMLfiles, cascading style sheets, and dynamic HTML, the approaches explainedin this book do not use any specific tools beyond Windows Notepad andMicrosoft's HTML Help Workshop (free and downloadable from theMicrosoft Web site). The idea is that you will get "under the hood" andunderstand what you are doing, rather than relying on knowledge that athird party built into their tool. You may want to use one of the manyavailable tools, but a knowledge of HTML Help itself will allow you to betterwork around the "bugs" and limitations of the tools and to take advantageof new capabilities before the tools can incorporate them.
This book should provide everything you need to know to efficiently createan attractive and useful compiled project in Microsoft's HTML Helpwhether that project be for online user assistance or for a self-containedebook. You can learn how to create the necessary HTML code, cascadingstyle sheets, and dynamic HTML scripts, in addition to how to manipulatethe HTML Help Workshop to add navigational functions (table of con-tents,index, full-text search) and compile the completed project.
New users can learn:
More advanced users can discover:
This book is not meant as a stand-alone work on HTML, DHTML, or CSSfor general use on the World Wide Web. Its applications are focused onuses within HTML Help.
Within the Help authoring universe, this book focuses on compiled HTMLHelp as implemented on Microsoft Windows platforms (95, 98, NT, 2000,and forward). Although much of the information on HTML Help (and allof the information on the HTML, CSS, and DHTML) applies to other productswritten in HTML, this book does not provide any specific informationon HTML-based (uncompiled) Help, JavaHelp, or other variations of onlineuser assistance systems; nor does it address questions pertinent to help onoperating systems other than Windows.
Finally, this book is meant for authors, not program developers, and sodoes not delve into the mysteries of the HTML Help API that developersuse to connect an application to an HTML Help file. For developerinformation, I strongly recommend the MicrosoftTM Developer Network(MSDNTM), available online at msdn.microsoft.com, with more extendedcontent available by subscription from Microsoft.
This book begins with an overview of the HTML Help concept and a completewalk-through of a sample project. Then the next three chaptersonHTML, CSS, and DHTMLexplain the three core Web technologies usedin HTML Help. Learning these technologies and applying them to yourprojects gets you set up for rapid content and product development. Thesechapters are presented from the simplest technology (HTML) to the mostcomplex (DHTML), but you should find yourself using them in an iterativefashion as you create templates for your HTML Help topics, enhance themwith CSS and DHTML, then return to the basic HTML pages to add moreinformation and to the CSS and DHTML to add new formats supportingthe new content. Each chapter closes with a section explaining the ways inwhich HTML Help specifically works with and clashes against the technologyalong with workarounds, where available. The final section of fivechapters focuses on HTML Help-specific elements built within the HTMLHelp Workshop itselfthe project file, the table of contents, navigationalelements (such as indexes, full-text search, and related topics), and mergingmodular filesbefore describing the steps necessary to distribute thefinal product. More specific chapter descriptions follow.
Chapter 1, "It's Not Just Help, It's HTML Help" is the chapter you'rereading now. It provides general background describing what HTML Helpis, how it can be enhanced with other technologies, and an overview ofthe remaining chapters.
Chapter 2, "So How Does It Work?" supplies a hands-on "Process &Product Overview." Based on a belief in learning by doing, this chapterpresents a walk-through of all the procedures required to create an HTMLHelp project. The chapter works through every step of the process, fromassessing your audience and choosing your tools; through building the stylesheets, dynamic HTML, HTML topics, table of contents, and index; andcloses with a description of the procedures required to compile the projectand prepare it for merging with other projects. Along the way, this chapterincludes a case study of an HTML Help system that Hewlett-Packardshipped with a Windows NT application. In addition, the chapter walksyou through the steps required to create the sample HTML Help systemon a gardening topic. Sample files required for the project areposted on the book's companion web site, www.jmek.net/html_help
Chapter 3, "Bringing It Together: HTML Templates & Topics," providesboth the starting and ending points for the builder of HTML Help systems.It starts out the system by helping you identify and design the templateswhich will define the overall structure of your topic pages before youenhance them with CSS and DHTML. It ends the system building byteaching the HTML that structures the information content as you writeeach topic page. But this is a cyclical process as new content suggestsalterations to the template, which in turn provides new possibilities for thecontent and its presentation. This chapter evaluates some of the mostpopular tools for creating HTML, including third-party software as well asthe HTML Help Workshop's facilities. The chapter then describes the basicconcepts of writing HTML (even in a plain text editor) and discusses thesyntax for two dozen tags commonly used in HTML Help. It also offerscut-and-paste code "recipes" for standard online Help formats.
Chapter 4, "Doing It In Styles: CSS; Cascading Style Sheets," exploresthe wonders of adding formatting to Web pages with the same sophisticationthat style sheets offer in word processing and desktop publishing pro-grams.Cascading style sheets define the look of your HTML Help system'slook and feel quickly and efficiently, allowing changes to a single style sheetto automatically flow throughout hundreds of HTML pages. This chapternot only describes the basic concepts underlying CSS, it also presents relevantsyntax, values, and examples for some 50 CSS properties.
Chapter 5, "Making Waves: DHTML (Dynamic HTML)," uses JavaScriptto add dynamics to the style and structure of your HTML topic pages. Thischapter explains what DHTML is and what it does, together with its ad-vantagesover other interactive technologies. It walks you throughMicrosoft Internet Explorer's DOM (Document Object Model), discussingthe objects, properties, values, methods, parameters, and events most commonlyused in HTML Help, along with "recipes" ready to cut and paste intoyour own HTML Help system.
Chapter 6, "Creating Magic: The HTML Help Project File" introducesthe project file, the primary container for information about and pointersto all elements of the HTML Help project. This chapter explains how tocreate a project file (in the HTML Help Workshop or a text editor), integratingthe various topic files with the table of contents, index, and searchfeatures before compiling the project. Special attention is given to windowtypes, Workshop definitions specifying the size, placement, and otherattributes of the primary and secondary HTML Help windows.
Chapter 7, "Navigating the Waters: Table of Contents" delves into thetable of contents, one of the primary navigational elements in HTML Helpsystems. The expanding table of contents is an integral part of the standardHTML Help window, remaining synchronized and available wheneverthe system is open. This presents a distinct advantage over earlier onlineHelp implementations, where the contents disappeared and reappeared ina never-ending dance with the topic pages. HTML Help's contents alsoallows presentation of links from other files in a merged modular system.
Chapter 8, "Out of Many, One: Merging Modular Files" describes theconcepts and procedures required to merge multiple HTML Help f iles intoone apparently seamless system. These systems support the creation of"plug-in" modules that can be sold or downloaded separately, but still appearas part of the main HTML Help in the table of contents, index, andsearch facilities. They are also useful in updating content on the fly and inmanaging extremely large systems.
Chapter 9, "Accelerating Links: Cross-Referencing Options" presentsnavigational options beyond the table of contents. This chapter explainshow to create an index, full-text search, and other methods for cross-referencinginformation in your HTML Help system that are not available withthe standard links of basic Web site technology.
Chapter 10, "Making It Happen: Distribution & Installation" detailsthe steps required to let users access completed HTML Help systems. Thischapter describes the vagaries of HTML Help installation on various Windowsreleases, including Windows 2000. It also lets you look "under thehood" at some of the libraries, executables, and ActiveX® controls that enableHTML Help on the end user's system.
