Table of Contents 
Previous Chapter 20 SDT On-Line Help
This chapter is a reference to the on-line Help utility that is available in the SDT graphical tools.
The following topics are covered:
- General functionality
- FrameMaker specific functionality
- Mosaic specific functionality
- Netscape specific functionality
- SDT Help Viewer specific functionality
SDT includes a context-sensitive function that displays, on request, graphical information which provides instructions about how to take advantage of the graphical SDT tools.
This section summarizes the on-line help functions that the SDT tools provide.
The SDT tools' Help menu includes the following commands:
For more information on this topic, see "Help Menu" on page 1033 in chapter 21, The SDT Graphical User Interface.
Each dialog in SDT has a Help button that provides access to the manual page where the dialog is described. For more information on dialogs, see "Modeless Dialogs" and "Modal Dialogs" on page 1041 in chapter 21, The SDT Graphical User Interface.
The SDT Help facility requires at present time one of the following viewers to be installed in the user's computer environment:
- FrameMaker (TM) / FrameViewer / FrameBuilder(1)
In this document, the term Frame is used to denote any of these products.
- NCSA Mosaic(2)
- Netscape(3)
- The SDT Help Viewer (included in the SDT distribution).
To have the SDT Help Tool function properly, the SDT user or SDT system manager is responsible for including these viewers in his computer environment and setting up the SDT environment (the SDT environment is set up with The Preference Manager).
Telelogic's help desk may provide information about how to acquire the FrameMaker, FrameViewer, FrameBuilder, NCSA Mosaic or Netscape environments. The address and telephone number to Telelogic Customer Support may be found on the front page of any of the SDT manuals.
When requesting Help from SDT, the PostMaster supervises the communication. On a heavily loaded computer system, the Help Viewer may fail to respond within the time limit specified by the environment variable STARTTIMEOUT. When this occurs, a message is appended to the console window. The environment variable should be adjusted to a higher value to match the typical response times for the computer system where SDT and the Help Viewer are running.
-----------------------------------------------------------------
Note:
Installing the Frame Help files is optional when installing SDT.
-----------------------------------------------------------------
When taking advantage of a Frame viewer and requesting help on a topic, SDT provides access to the manual pages, with the same appearance as printed on paper together with hypertext navigation and search facilities.
In addition, the user's documentation is structured as a hypertext read-only manual that is also possible to use on its own, without control from SDT. A book file with the name sdt3.bok contains all files that build up the SDT user's documentation. When installing SDT, the Frame files are stored in a subdirectory to the SDT root directory, with the name fmhlp.
For a thorough description of the functionality that the Frame products provide, we refer to the Frame user's documentation that is included in the respective product.
This section summarizes the properties and built-in functions in the Frame files.
The Frame documents are designed to form a pile of windows, positioned on top of each other when opened. The following Frame View Options apply:
- Borders off
- Text symbols off
- Rulers off
- Grid lines off
- Color view 1 (cutoff white, other colors visible). The color blue is by convention reserved for hypertext links and buttons.
The documents include the following hypertext facilities:
- Hypertext links are available in text. Text that is associated to a link is by convention shown in blue color and underlined.
- Each chapter has its local table of contents. The entries in this table of contents have hypertext links to the corresponding sections.
- Each volume includes a global, less detailed table of contents, with hypertext links to the chapters contained in the volume. See chapter 3, Documentation Guide, in the volume SDT 3.01 Release and Documentation for a description of how the information is organized in terms of volumes and chapters.
- Index entries provide hypertext links as well. The index is available in a document of its own.
On each page, beneath the text flow and above the footer is a row of handy buttons that may be used as accelerators for frequent operations.
Figure 194 : Quick Buttons in Frame Documents.
The quick buttons are the following:
- Table of contents: Transfers the flow to the table of contents for the chapter currently in view.
- <Double left arrow>: Browses back in stack. (Frame keeps track of the hypertext navigation in a stack.)
- <Left arrow>: Shows the previous page in chapter.
- <Right arrow>: Shows the next page in chapter.
- Help: Shows a pop up menu with menu choices that provide help on how to use the Frame hypertext manual.
- Online Manuals: Shows a pop menu with the on-line manuals that are included in the distribution. Selecting one of these menu choices opens a new flow in Frame, that will use its own navigation stack. This makes it possible to open and navigate in multiple flows.
- Close: Closes the window currently being displayed.
- Close All: Closes all open windows in the stack.
Frame allows to search for various objects (i.e. a text string) in the document currently in view.
PostScript printouts may be generated from Frame. For a more comprehensive description of the printing function and its options, we refer to the Frame user's documentation.
In the SDT installation, a number of prepared PostScript files are included. You may use these files for producing hard copies of the SDT manuals (a document may be split up on multiple files). The page size and scaling factor that is used when preparing the files makes them suitable to print on A4 or US Letter paper. The documents are paginated using an even page count in order to make it possible to use both paper sides when printing.
The files that are included in the SDT 3.01 distribution comply to the storage format used by FrameMaker version 4.0.
It is possible to have SDT use a specific instance of the Frame programs when requesting on-line Help from SDT and when importing SDT printouts into FrameMaker (with the Import into Frame Maker, see chapter 29, The Print Utility).
This facility is useful in particular when the user's computer environment supports for instance both FrameMaker and FrameViewer, in which case FrameViewer may be used for displaying on-line Help and FrameMaker / FrameBuilder may be used for importing SDT printouts into a Frame document.
The X Window root window has an atom (property) that governs how Frame and SDT communicate. The name is arbitrary, but must defined both in SDT and Frame.
In the remains of this section, we have selected to use the names _Frame_SDT_Help and _Frame_SDT_Import.
To have SDT and Frame behave in accordance, the user should specify what resource to use by SDT when starting the Frame program.
The resource values should be entered in the SDT resource file (in which case all users are affected) or in a suitable user X resource file.
The resources are named
sdthelp*rpcProp
and
sdtfmimp*rpcProp
Example 25 : X Resources for SDT Help
(X resource file sample)
...
sdthelp*rpcProp: _Frame_SDT_Help
sdtfmimp*rpcProp: _Frame_SDT_Import
...
There are multiple ways to set up Frame. See for instance the FrameMaker documentation that describes how to change setup files, chapter "Changing Resources". The resource Maker.rpcProp may be used for this.
Alternatively, the user may create an executable script that is used as startup script for the Help Viewer, as specified with the Preference Manager.
Example 26 : Specifying Frame Help Viewer
Assume the user has specified the preference parameter HelpViewer as $HOME/bin/MyFMViewer
MyFMViewer is in turn a script file with the following contents:
#!/bin/sh
exec iviewer -rpcProp _Frame_SDT_Help
The SDT documentation is created using FrameMaker. The files that the documentation is composed of are also available in HTML(4) format. Although the preferred format is Frame because of the over-all better impression, we encourage SDT users who do not have and are not planning to include Frame in their computer to run an HTML browser since the essential functionality is supported.
----------------------------------------------------------------
Note:
Installing the HTML Help files is optional when installing SDT.
----------------------------------------------------------------
The work performed by Jon Stephenson von Tetzchner at the Norwegian Telecom Research was of great value when converting from Frame format to HTML.
When using an HTML browser (such as NCSA Mosaic, Netscape or the SDT Help Viewer) as the Help viewer tool in SDT, the functionality is reduced in comparison to what is available in Frame, because of the nature of HTML which does not support all concepts that are possible to define in the Frame documents.
- Hypertext links in the text flow are supported.
- Hypertext links in files that are generated by FrameMaker are not supported. This restriction implies that indexes and local (chapter) table of contents are not provided. There is, however, a global table of contents (see below).
- At the top of each HTML file, hypertext links to a global table of contents and to the previous chapter (or the previous part of the same chapter) are provided.
- At the bottom of each HTML file, hypertext links to a global table of contents and to the next chapter (or the next part of the same chapter) are provided.
- The typographic facilities (font faces, sizes and styles) that are defined in the HTML files are less extensive than in Frame. Because of this, a default translation scheme is adopted, that converts the typography defined in the Frame documents into typography available in HTML. The implication of this is that text sections may be given a different appearance.
- The page concept does not exist. Because of this, there is no support for headers and footers and quick buttons on each page.
The HTML files that are enclosed in the SDT 3.01 distribution conform to the definition of HTML level 0.
The Mosaic Back button corresponds to the <Double left arrow> button in the SDT Frame documents.
Graphics (such as pictures and screendumps) are displayed on demand. The presence of a graphical object is indicated by the link (fig), underlined. A single button click on the link displays the picture in a window of its own.
Mosaic supports searching for a text string in the document currently in view.
Plain text, formatted text, PostScript and HTML printouts may be generated from Mosaic. For a more comprehensive description of the printing function and its options, we refer to the manual that is available on the Mosaic Help menu.
The SDT distribution also contains a number of prepared PostScript files. See "Print" on page 1015 for more information.
Netscape is an HTML browser which works much like Mosaic. Please see "NCSA Mosaic Specific Functionality" on page 1018 for more information.
-----------------------------------------------------------------
Note:
SDT requires Netscape version 1.1 or later.
To be able to use Netscape with SDT, Netscape must be started out
side of SDT before the SDT help facility is invoked.
-----------------------------------------------------------------
The SDT Help Viewer visualizes the SDT HTML help files and allows navigation via hyperlinks.
--------------------------------------------------------------
Note:
The SDT Help Viewer is not a general HTML browser. It only sup
ports the SDT help files.
--------------------------------------------------------------
The help documents are rendered using the SDT preferences ScreenFontFamily and Scale. To change the size of the text you may take advantage of the scaling quick buttons.
Graphics (such as pictures and screendumps) are displayed on demand. The presence of a graphical object is indicated by the link (fig) or (IMG), underlined. A single button click on the link displays the picture in a separate window. The same window is used for all graphics, i.e. the window does not have to be closed after viewing a graphic.
The following quick buttons are special to the SDT Help Viewer. The general quick buttons are described in "Quick Buttons" on page 1035.
----------------------------------------------
(fig) Open
Opens a new SDT help file to browse.
(fig) Go Back
Browses back in the hyperlink stack.
(fig) Go Forward
Browses forward in the hyperlink stack.
----------------------------------------------
-------------------------------------------------------------------
File > Open
Opens a new SDT help file to browse.
File > Exit
Exits the SDT Help Viewer.
View > Set Scale
Sets the scale to an explicit value.
Navigate > Go Forward
Browses forward in the hyperlink stack.
Navigate > Go Back
Browses back in the hyperlink stack.
Window > New Window
Clones the current window, with the same contents as the current.
Window > Close Window
Closes the current window (and exits if no other windows are open).
-------------------------------------------------------------------
Footnotes
- (1)
- FrameMaker / FrameViewer / FrameBuilder is a desktop publishing environment, developed and marketed by Frame Technology Corporation. The SDT manuals are created with FrameMaker.
- (2)
- NCSA Mosaic is an Internet information browser and World Wide Web client. NCSA Mosaic was developed at the National Center for Supercomputing Applications at the University of Illinois, Urbana-Champaign.
- (3)
- Netscape is an Internet information browser and World Wide Web client. Netscape is developed by the Netscape Communications Corporation.
- (4)
- HTML stands for Hyper Text Markup Language.
Table of Contents 
Next Chapter
