You are previewing Creating Effective JavaHelp.
O'Reilly logo
Creating Effective JavaHelp

Book Description

Effective, instantly available online help is a requirement for today's interactive applications. Until now, Java application developers have been forced to develop their own help system. That's no longer necessary. With the release of JavaHelp™, there is a complete and standard online help system for the Java™ platform. Creating Effective JavaHelp covers the main features and options of JavaHelp. It shows how to create a basic JavaHelp system, prepare help topics, and deploy the help system in an application. Written for all levels of Java developers and technical writers, the book takes a chapter-by-chapter approach to building concepts. It imparts a complete understanding of how to create usable JavaHelp systems and integrate them into Java applications and applets. Topics covered include:

  • Understanding JavaHelp

  • Creating your first HelpSet

  • Planning the JavaHelp project

  • Preparing Help topics

  • Creating HelpSet data and navigation files

  • Enhancing the HelpSet

  • Using the JavaHelp API for advanced presentation options

  • Deploying the help system to your users

  • Using third-party help-authoring tools

Table of Contents

  1. Creating Effective JavaHelp
    1. Preface
      1. Audience
      2. About This Book
      3. Assumptions This Book Makes
      4. Conventions Used in This Book
      5. Comments and Questions
      6. Acknowledgments
    2. 1. Understanding JavaHelp
      1. What Is JavaHelp?
      2. Using JavaHelp for Online Documentation
        1. Why Use JavaHelp for Online Help?
        2. Comparing JavaHelp with Other Help Systems
        3. Using JavaHelp for General Online Documentation
      3. Understanding the Files in a HelpSet
      4. Following the JavaHelp Process
      5. Installing JavaHelp on Your Computer
      6. Seeing JavaHelp in Action
        1. Starting the JavaHelp System
        2. Working with the JavaHelp Interface
        3. Using Toolbar Controls and Menus
        4. Navigating Through the JavaHelp System
        5. Viewing Help Topics
      7. Deciding How to Present a HelpSet
        1. Using Standalone Help
        2. Using Context-Sensitive Help
        3. Using Embedded Help
      8. Deciding How to Install a HelpSet
        1. Local Application
        2. Network Application
        3. Java Applet
        4. Java Product Suite
      9. Encapsulating HelpSet Files
      10. Finding More Information on JavaHelp
    3. 2. Creating Your First HelpSet
      1. Creating the HelpSet’s Directory Structure
      2. Creating HelpSet Data and Navigation Files
        1. Creating the HelpSet File
        2. Creating the Map File
        3. Creating the Navigation Files
          1. Creating the TOC file
        4. Creating the Index File
      3. Creating Help Topic Files
      4. Checking Your Work
      5. Testing the Finished HelpSet
    4. 3. Planning the JavaHelp Project
      1. General Planning Tasks
        1. Defining the Audience
        2. Determining the Audience’s Needs
        3. Planning Integration with Hardcopy Documentation
        4. Creating an Outline
          1. Example of a general outline
        5. Testing Your Outline
        6. Scheduling Project Tasks
      2. Planning Tasks Specific to JavaHelp
        1. Deciding How to Present the HelpSet
        2. Deciding How to Install the HelpSet
        3. Outlining the File and Directory Structure
          1. Structuring HelpSet data and navigation files
          2. Structuring topic and field-level help directories and files
          3. Structuring images and multimedia files
          4. Structuring pop-up and secondary window files
        4. Planning the Navigation Components
    5. 4. Preparing Help Topics
      1. Planning Your Help Topics
        1. Assigning Work to Help Authors
        2. Organizing Information into Help Topics
        3. Obtaining Approval from Team Members
      2. Creating Help Topics and Applying Appropriate HTML Tags
        1. Naming the HTML Files
        2. Applying Formats to Text
        3. Using Links
      3. Writing Effective and Meaningful Help Topics
        1. Understanding How Users Read Online Help
        2. Chunking Information
        3. Writing the Topic Content
        4. Setting the Topic Length
        5. Designing the Topic Title
          1. Using the <title> tags to specify the topic title
      4. Using Preexisting HTML Topic Files
    6. 5. Creating HelpSet Data and Navigation Files
      1. Understanding XML
      2. Creating the HelpSet File
        1. Understanding the HelpSet Data Elements
        2. Understanding the Navigation Component Elements
      3. Assigning Map IDs to Help Topics
        1. The Map File
        2. Naming the Map File
        3. Structuring the Map File
      4. Specifying the Navigation Components
        1. Creating the Table of Contents
          1. Building the JavaHelp TOC
          2. Creating the TOC elements
          3. Creating help topic categories
          4. Help topics for category entries
          5. Creating a top-level TOC entry
        2. Creating the Index
          1. Building the JavaHelp index
        3. Creating the Word-Search Index
    7. 6. Enhancing the HelpSet
      1. Creating Pop-up and Secondary Windows
        1. Differences Between Pop-up and Secondary Windows
        2. Programming Pop-up and Secondary Windows
          1. Specifying the form of the link
            1. Linking with a button
            2. Linking with a text string
            3. Linking with an image
          2. Defining the window’s properties
          3. Defining the window’s content
      2. Customizing the Navigation Facility
        1. Changing Navigation Components’ Tool Tips
        2. Excluding Navigation Components
        3. Rearranging Navigation Component Tabs
        4. Customizing the TOC
        5. Applying Advanced Word-Search Index Features
          1. Changing pathnames of topic files
          2. Identifying specific topic files to index
          3. Modifying stopwords
          4. Combining multiple configuration commands
      3. Merging HelpSets
        1. Using the <subhelpset> Element
        2. The Drawbacks of Merging
          1. Overcoming the drawbacks
        3. Managing Projects with Merged HelpSets
    8. 7. Using the JavaHelp API for Advanced Presentation Options
      1. The TypeFacer Application
      2. Invoking Help with a Button, Menu Item, or Key
      3. Using Screen-Level Context-Sensitive Help
        1. Programming Screen-Level Context-Sensitive Help
        2. Keeping an Overview Help Topic
      4. Using Field-Level Context-Sensitive Help
        1. Programming Field-Level Context-Sensitive Help
      5. Embedding Help into the Application
        1. Understanding Embedded Help
        2. Programming Embedded Help
        3. Programmatic Control of the Viewer Topic
          1. Implementing context sensitivity
          2. Hiding embedded help
    9. 8. Deploying the Help System to Your Users
      1. Encapsulating the HelpSet
        1. Creating the JAR File
      2. Delivering All the Required Files
      3. Ensuring Basic Java Support
    10. 9. Using Third-Party Help-Authoring Tools
      1. How JavaHelp Relates to Third-Party Tools
      2. How Third-Party Tools Work
        1. ForeHelp
        2. Doc-to-Help and RoboHELP
    11. A. HelpSet Tags
      1. Map File
      2. TOC File
      3. Index File
      4. HelpSet File
    12. B. Lightweight Component Tags
      1. Pop-up and Secondary Windows
        1. Elements and Attributes
        2. Parameter Names and Values
    13. C. The JavaHelp API
      1. Classes in Package
        1. BadIDException
        2. CSH
        3. DefaultHelpBroker
        4. DefaultHelpModel
        5. FlatMap
        6. HelpBroker
        7. HelpModel
        8. HelpSet
        9. HelpSetException
        10. HelpUtilities
        11. IndexItem
        12. IndexView
        13. InvalidHelpSetContextException
        14. InvalidNavigatorViewException
        15. JHelp
        16. JHelpContentViewer
        17. JHelpIndexNavigator
        18. JHelpNavigator
        19. JHelpSearchNavigator
        20. JHelpTOCNavigator
        21. Map
        22. NavigatorView
        23. SearchHit
        24. SearchTOCItem
        25. SearchView
        26. TextHelpModel
        27. TOCItem
        28. TOCView
        29. TreeItem
        30. TreeItemFactory
        31. TryMap
        32. UnsupportedOperationException
      2. Classes in Package
        1. EventListenerList
        2. HelpModelEvent
        3. HelpModelListener
        4. HelpSetEvent
        5. HelpSetListener
        6. TextHelpModelEvent
        7. TextHelpModelListener
    14. D. Source Listing
    15. 10. Glossary
    16. Index
    17. Colophon