Getting the Best Results with RAD Studio Online Help

By: Kris Houser

Abstract: Describes how to use the help and its viewer, and how to search the help successfully.

Do you want to optimize your chances of success when you search the RAD Studio online help?  This article presents several easy ways to improve your access to online help by leveragung the features of the RAD Studio help viewer (the Microsoft document explorer, Dexplore.exe).

You can choose specific help volumes (such as local help or MSDN Online) to be used in the Search and Index functions. For example, you can limit your searches to include only the local help provided by RAD Studio, and you can specify that the help viewer displays local help first or help from online providers first. The help viewer has a filter that enables you to narrow your search even further; see suggested filter settings in "Executive Summary" and under "Using the Help Filters."

    Executive Summary

Use the following settings to display only RAD Studio help topics in the help viewer:

  • On Tools>Options>Help>Online in the help viewer:
    • Select Try local only, not online in the When loading Help content field
    • Make sure that Local Help is selected in the Search these providers field
  • In the Filtered by field on the Index and Contents pane, select either:
    • RAD Studio
    • RAD Studio, Dinkumware C++, Indy

    Introducing the Help Viewer

The RAD Studio Help Viewer Window has two major panes. Here is the default window layout:

Hide image
Click to see full-sized image

  • The Index and Contents (TOC) pane is on the left-hand side. To switch between the Index and the Table of Contents, just click the Index or Contents tab at the bottom of the left-hand pane.
  • The topic display and Search pane is on the right-hand side. To open the Search dialog and the search results display, click the Search tab at the top of the right-hand pane (or the Search button in the toolbar).  When a topic is displayed, the title of the current help topic appears on the tab of the display pane (as well as inside the topic itself), and the topic's URL or help address is displayed below the title tab.

You can open the Search, Index and Contents features in three places in the help viewer:

  • By clicking the command (Search, Index, or Contents) in the Help menu
  • By clicking the toolbar button (Search, Index, or Contents)
  • By clicking the tab of the appropriate pane in the help viewer

You can close any of the tabbed panes by clicking the x in the upper right corner of the pane. 

To reopen a pane, click Search, Index, or Contents in either the Help menu or the help viewer's toolbar:

Hide image
Click to see full-sized image

 

    Using Basic Search, Copy, and Paste in the Online Help

SEARCHING INSIDE A HELP TOPIC: To search for text inside the topic currently displayed in the help viewer, choose Edit>Find in this Topic (Ctrl+F).

COPY AND PASTE TEXT: You can copy all or a selected portion of the contents of a help topic to the clipboard. Just highlight the text and use Ctrl+C or Edit>Copy. Then you can paste the captured help contents into an email, a text editor, or a bug report.

COPY AND PASTE HELP URLs: You can also copy the URL of a help topic (such as ms-help://embarcadero.rs2010/rad/What's_New_in_Delphi_and_C++Builder_2010.html) from the help viewer window. Then you can paste the URL into an email, a text editor, or a bug report. Citing the URL of a help topic can be very useful when reporting bugs you find in the online help. Later, anyone can paste the URL into the help viewer and display the topic in question. You can also paste a standard Internet URL address (such as http://www.embarcadero.com or http://docwiki.embarcadero.com/RADStudio/en/Main_Page) into the help viewer URL field. The help viewer is essentially an HTML browser similar to Internet Exlorer. 

    Using the Table of Contents

The Table of Contents provides an easy way to navigate the online help -- that is, if you are familiar with the organization of the Contents. You can use the Contents to browse through several libraries of help to find related topics.

The RAD Studio Contents is organized into three major libraries:

  • RAD Studio Topics
  • Libraries Reference
  • Code Examples (this includes descriptions of Product Samples)

Hide image
Click to see full-sized image
 

SYNCHRONIZING WITH THE TABLE OF CONTENTS

Clicking the Sync with Table of Contents button in the toolbar synchronizes the Contents pane with the displayed help topic:

Hide image
CodeGear

This button displays the Contents tab and places focus on the Contents entry that matches the current help topic. The Sync with Table of Contents button enables you to:

  • Explore closely related topics in the Contents.  You can easily see the topics that precede and follow the current topic.
  • Determine the context of a topic (Is this topic about Delphi, or is it about C++? Is this topic in the Delphi Language Guide or the Win32 Developer's Guide?).

The Sync with Table of Contents button is disabled when the current topic is not listed in the Table of Contents.

    Using the Index

The Index is another very useful way to search for topics in the help. 

  • FILTERS: You can set the Index Filtered by field to include or exclude help for third party products and the MS Windows Platform SDK. For details, see "Using the Help Filters."
  • TOPIC TITLES: The title of every help topic appears in the Index.  If you know the title of a help topic you want to see, you can easily find it by typing the first few words into the Look For field of the Index. Entering keywords in the Index is one way of searching the help.
  • VCL/FMX/RTL:  Every unit name (such as System or Forms) appears in the Index, followed by all the members of the unit and the subject matter topics under that heading, like this:

 Hide image

Click to see full-sized image

  • Libraries (VCL/FMX/RTL): Similarly, the Index lists every member (each class, function, property, method, event, and so forth).  For example, this means you can find the help for Forms.Application by looking under Forms.Application in the Index, or alternatively:

Application

Forms

    Searching the Help Successfully

GENERAL STRATEGY: To get the best search results, start by consulting the Index.  Then use Search if the Index does not lead you to the information you seek. If possible, enter an exact string inside double quotes to help narrow the search.

Many people are reluctant to use the Search mechanism in the help because a search might yield hundreds of topics. In some instances, however, the only way to find information is by using the Search, not by using the Index or Contents, so specifying a search string is key.

WHAT THE SEARCH COMMAND DOES: The Search command searches every topic and can find exact text inside a topic. (To search for an exact string, place the string inside quotation marks, such as "Project Manager".) On the other hand, the Index and Contents are essentially built from tags inside the help topics. For example, a help topic that only once mentions CodeGuard might not be indexed under CodeGuard. But if you do a Search on CodeGuard, that file would be listed in the results.

SORTING YOUR SEARCH RESULTS: Located above the search results are two sorting fields that give you some control over the order of the results, Sort by and Sorted in ascending/descending order:

Sort by Rank and Order

Use the Sort by field to specify that the results are to be arranged by:

  • Rank (the strongest match is listed first)
  • Source (results are listed alphabetically by source, such as Blackfish SQL or RAD Studio VCL Reference; click the associated Sorted in ascending/descending order to reverse the order)
  • Contains code (topics that contain code examples are listed first)
  • Title (results are listed alphabetically by title; click the associated Sorted in ascending/descending order to reverse the order)
  • Locale (results are listed by locale; not supported in typical installations)

 The following Search example yields the maximum numbers of hits (500 local hits in RAD Studio help, plus hundreds of hits in 3rd party and online help):

Hide image
Click to see full-sized image

Although a net of 500 topics seems daunting, keep in mind that the first topics in the list are the strongest matches to your Search string. If you scan the first screen of topic titles, you can eliminate many of them without opening the topics, and open only the ones that have likely sounding titles. If you open a topic and wonder what general area it came from (is it from the Delphi Language Guide? the C++ Language Guide? the dialog help? the VCL/RTL?), you can use the Sync with Table of Contents button to see where the topic resides in the contents.

The 3rd party and online help sources (such as MSDN Online) are conveniently presented on separate tabs in the Search results display.  You can, however, eliminate them entirely if you want to do so.

    Excluding 3rd Party Help from the Index and Contents

You can control whether third party help is included in the Index and Contents

As typically installed, RAD Studio online help contains the help for several 3rd party products, such as Internet Direct (Indy) and the Dinkumware Library. When the filter for the Index and Contents of the help is set appropriately, the help for these products is integrated into the help Index and appears as separate volumes in the Contents. By adjusting help viewer options, you can give preference to either local help (RAD Studio help) or help from online sources, and you can completely eliminate external help from Search results if you so desire.

The Search results in the following example contain only the RAD Studio help, no external help (only the "Local Help" tab is displayed). This example uses the settings described in "Executive Summary" and in this section:

Hide image
Click to see full-sized image

The following paragraphs describe the settings that enable you to specify the help volumes to be used in the Index and Search on the help viewer.

    Adjusting Your Search Using the Tools>Options Dialog Box

Use the Tools>Options>Help>Online dialog box to specify whether Search will include external sources or only RAD Studio help (local help).  The "Search these providers" settings illustrated in the following screenshot theoretically permit the inclusion of online and 3rd party help.  However, only local help (RAD Studio help) is included in Search results because"Try local only, not online" is selected in the "When loading Help content" field (even though other help providers are checked in "Search these providers"):

 Hide image
Click to see full-sized image
 

The following table summarizes the options that you can set on the Tools/Options/Help/Online dialog box:

Tools>Options>Help>Online Option Group Settings Description
When loading Help content Try online first, then local Places external (online) help sources first in Search results.
  Try local first, then online Lists RAD Studio topics first in Search results.
  Try local only, not online* Excludes external (online) help sources. Includes only RAD Studio help in Search results. (Recommended setting.)
Search these providers: Local Help
MSDN Online
Codezone Community
Questions
These are the external (online) help volumes that you can specify to be searched. None of the providers in the list are searched if you have selected Try local only, not online in the "When loading Help content" field. Use the Up/Down arrows to move the selected provider up or down in the list.
Codezone Community: Download Provider List Theoretically lists external (online) domains that you can include in or exclude from your help searches. As shipped, the help viewer might have no available  Codezone Community providers.  Note that if you select only Local Help in the Search these providers box, the Codezone Community list is ignored.

* NOTE: ELIMINATING THIRD PARTY HELP FROM YOUR SEARCHES
To see only Embarcadero RAD Studio help in your Search results, and to eliminate all external (online) help sources, select Try local only, not online in the When loading Help content field on the Tools>Options>Help>Online dialog box.

    Using the Help Filters

  • Index and Contents filters (Filtered by field on the left-hand pane of the window):

Hide image

INDEX AND CONTENTS FILTERS: These filters serve to eliminate everything from the Index and Contents except for the subject matter indicated in the filter, as follows:

  • (No Filter) -- Includes all RAD Studio help, along with third-party help (such as TeeChart and Rave Reports), and MS Window Platform SDK, with .NET Framework SDK for 2007 products only
  • Microsoft Windows Platform SDK -- includes only Microsoft Windows Platform SDK, and (for 2007 products only) the .NET Framework SDK; does not include any RAD Studio help
  • RAD Studio - Includes all of the help for all RAD Studio personalities (Delphi and C++Builder)
  • RAD Studio, Dinkumware C++, Indy -- Includes all of RAD Studio help, the Dinkumware Standard C++ Library, Internet Direct (Indy), and Rave Reports.

TIP: To include all of RAD Studio help, select the RAD Studio filter or the RAD Studio, Dinkumware C++, Indy filter. Both of these filters include help for the VCL, FireMonkey, and all personalities (Delphi and C++Builder).

    Customizing Your Help Viewer

To select the commands and toolbars that will appear in the help viewer, click Tools>Customize:

Hide image
Tools/Customize

 

On the Tools/Customize dialog box, you can specify and rearrange the commands that appear in the menus and toolbars of the help viewer, create new menus of your own, specify whether shortcuts are to appear (such as Ctrl+C for Copy), and create new shortcuts of your own.

    Rearranging the Help Window

To close and reopen the various panes in the help viewer, use any of the following:

  • Toolbar buttons (Search, Index, Contents, Help Favorites)
  • Context menu commands (right-click the title bar of a pane in the help viewer)
  • Tabs on the panes in the help viewer
  • Commands on the Window menu and Help menu

Many combinations are possible, and this article describes only a few. Experiment yourself to find the combination that you like.

To move the various panes of the help viewer window:

  • Click the title bar of the Contents or Index pane to undock the pane.
  • Drag the undocked pane to another area in the viewer. You can also move an undocked pane outside of the viewer entirely.
  • Double-click the title bar to return an undocked pane to its default location.

To manage the appearance and layout of the help viewer window, use the Window menu commands (Floating, Dockable, Tabbed Document, Autohide, and Hide) in the help viewer. Try different arrangements of the help viewer panes to suit different needs. To return the help viewer window to its original, default layout, click Window>Reset Window Layout.

CLOSING AND RESTORING PANES: To close a pane in the help viewer, either click the x in the upper right corner of the pane, or right-click the title bar of the pane and select the context-menu command Hide. To restore a pane that you have hidden or closed, either click the appropriate toolbar command or choose the appropriate Help menu command (Search, Contents, Index, or Help Favorites).

USING AUTO HIDE: The Auto Hide command is on the context menu that displays when you right-click the title bar of a pane in the help viewer. Auto Hide hides the pane, but the help viewer still displays a vertical tab on the side of the pane. Auto Hide is useful for expanding the topic display area without resizing the window.

To temporarily view a pane that has been Auto-Hidden, either mouse-over the vertical tab or choose the appropriate Help menu command (Index, Contents, Search). Clicking the vertical tab of an Auto-Hidden pane restores the pane but retains the Auto Hide property and the vertical tab. To revert the Auto Hide property for a pane, either right-click the title bar of the pane or select the Window menu, and toggle Auto Hide.

The following URL is the address of a Microsoft help topic ("How to Manage Help Windows") that more fully describes how to manage the help windows of the Dexplore help viewer:

ms-help://borland.bds5/MS.NETFramework.v20.en/MS.Dexplore.v80.en/dv_dexplore/html/21340e12-b422-466b-8132-73cc27587cc7.htm

    Adding Help Favorites

You can add your own Help Favorites tab to the help viewer, just as you bookmark Web pages in a Web browser. When a topic is displayed that you want to save, just right-click the help topic in the viewer, and select Add to Help Favorites from the context menu.

The Add to Help Favorites command does the following for you:

  • Creates the Help Favorites tab if it is not yet present in the help viewer
  • Adds the title of the current help topic to the Help Favorites tab, under the Help Topics node

When you click a topic title on the Help Favorites tab, you go directly to the help topic that you have designated as your favorite.

HELP FAVORITES CONTEXT MENU COMMANDS: The Help Favorites page has a small set of commands for managing the contents of the page. The following four icons/commands are available on both the context menu and on the toolbar of the Help Favorites page:


Hide image
CodeGear

  • Move Up
  • Move Down
  • Rename
  • Delete

Renaming favorite topics can help you remember their contents. For example, you might change "Features of Widgets" to "Widget Hyperdrive" so that you can easily remember what is important to you in the help topic. (When you change the title of a topic, the title is changed only on the Help Favorites page, not in the Contents, the Index, or in the help topic file itself.)

ADDING SEARCH RESULTS TO HELP FAVORITES: Besides saving help topics as Help Favorites, you can also save the results of Help Searches on the Help Favorites tab. Just click the Save Search button on the toolbar when the right-hand pane displays search results you want to keep. Saving Search results enables you to review the search results repeatedly, without having to repeat the Search command. You will find more information about Search commands later in this article.

    Useful Adjustments You Can Make in the Tools/Options Dialog Box

You can activate or deactivate several useful features of the help viewer by using the Tools>Options>Help>General dialog box:

Hide image
Click to see full-sized image

The following table summarizes the options that you can set on the Tools/Options/Help/General dialog box:

Tools/Options/Help/General Option Settings and Description
Show Help using You cannot select another viewer for RAD Studio help.
Show topic abstracts On: Displays topic summaries in the search results. Off: Displays only topic titles and source.
Reuse topic window On: Reuses the topic display window for subsequent searches. Off: Creates a new tab for each search. (Note that if you do view multiple topics or perform multiple searches with this option Off, the growing number of tabs can quickly become a nuisance in the help viewer.)
Highlight search terms On: Highlights search terms by placing a dark blue rectangle over search terms found in topics. Off: Does not highlight search terms.
Include partial searches in local search results: On: Displays topics that contain partial matches as well as exact matches to the search term. Off: Displays only topics that contain an exact match with the search term.
Online topic language You cannot select a language for the help that is different from your localized language version.

CHANGING COLORS: You can define the colors that the help viewer uses for text and for background. The colors you choose will apply to both the help viewer and Internet Explorer. For instructions on changing the colors, select Tools/Options in the help viewer and then press F1.

Copyright © 2012 Embarcadero Technologies, Inc.. All rights reserved.

Server Response from: ETNASC02