Building Enhanced HTML Help with Dhtml and CSS
Authors: Jeannine M. Klein
Venue:  (2000)

From the Book:PREFACE: 1. It's Not Just Help, It's HTML Help "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 Helpquite possibly, in a new format from Microsoft&reg; that is called compiled HTML Help. HTML Help goes miles beyond the boring yellow pages with tiny type that have become thedefacto 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&reg; and 2000&reg; and is evermore commonly used in applications that run on these platforms, includingMicrosoft&reg; 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 literatureand 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.Basic ideas their corollariesThe 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&reg; 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.The corollariesOne 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.A note on terminologyThe 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 enhanced propositionThe 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.A complete processThe presentation of HTML Help in this book suggests a complete processfor creating enhanced HTML Helpa 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 Helpan approachnot unlike the "componentization" currently advocated and practicedby many software development teams.Basic HTML Help+DHTML+CSS = Enhanced HTML HelpThe 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: built-in expanding and contracting, hierarchical table of contents, with the ability to merge contents f rom multiple projects; automatic index creation based on keywords in individual files or de-fined in the HTML Help project; ability to create shortcuts that open other Microsoft Windows pro-grams (or even specific locations within other programs); automatic full-text search without an additional search engine or any coding; ability to ship and run an entire system from a single file; in short, access to most Windows help capabilities. 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: dynamic content that can modify itself based on user response; Web graphic standards that support rich design with small file sizes; dynamic graphics that can change over time or in response to user interaction; in short, access to most Web-based capabilities.Finally, in addition to the Windows help and HTML capabilities, HTMLHelp brings its own rich set of functionality, including the following: Single tripane window simultaneously displays content and navigation. Synchronized table of contents allows users to visualize their location within the system's hypertextual structure. Boolean (AND, OR, NOT) capabilities are available in the full-text search pane.All combined, the equation adds up to rich online assistance or ebook publishingthat is, enhanced HTML Help system.Who should read this bookThis 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-adequatein fact, anenhancedHTML 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 Helpthe 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.What you can learn from this bookThis book should provide everything you need to know to efficiently createan attractive and useful compiled project in Microsoft's HTML Helpwhether 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: the structure and elements of compiled HTML Help systems functionality, tricks, and tips for using the HTML Help Workshop inner workings of the HTML Help table of navigation pane (table of contents, index, and full-text search) standard HTML markup and structure necessary to create HTML Help content, together with templates for creating HTML pages and information about two dozen standard HTML tags essential elements of cascading style sheets, including 50 frequently used properties for paragraph, font, list, and heading elements basic dynamic HTML coding in JavaScriptTM, with pre-canned code for pop-ups and other common itemsMore advanced users can discover: Microsoft's sitemap format used for HTML Help tables of contents and indexes window definitions, their meanings, parameters, and available values how to open HTML Help code and "tweak" elements not accessible via the HTML Help Workshop known bugs in the HTML Help system, together with "under-the-hood" tips and tricks for working around the bugs 50 CSS properties, together with the "gotchas" for the HTML Help implementation detailed information about the values and pitfalls of merged modular systems, together with step-by-step instructions for creating these systemsLimitationsThis 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.Chapter overviewsThis book begins with an overview of the HTML Help concept and a completewalk-through of a sample project. Then the next three chaptersonHTML, CSS, and DHTMLexplain 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 technologyalong with workarounds, where available. The final section of fivechapters focuses on HTML Help-specific elements built within the HTMLHelp Workshop itselfthe project file, the table of contents, navigationalelements (such as indexes, full-text search, and related topics), and mergingmodular filesbefore 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,... 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&reg; controls that enableHTML Help on the end user's system. nnn The ACM Portal is published by the Association for Computing Machinery. Copyright © 2010 ACM, Inc. Terms of Usage Privacy Policy Code of Ethics Contact Us Useful downloads: Adobe Acrobat QuickTime Windows Media Player Real Player