|
Common Desktop Environment: Help System Author's and Programmer's Guide
7 Command Summary
Contents of Chapter:
- Help System Commands
-
- Processing HelpTag Files (dthelptag)
-
- Command Syntax
-
- Command Options
-
- Parser Options
-
- Displaying Help Topics (dthelpview)
-
- Command Syntax
-
- Generating a Browser Help Volume (dthelpgen)
-
- Command Syntax
-
- Options
-
This chapter summarizes the command-line options available when the help commands are run manually in a terminal window.
Help System Commands
Desktop actions and data types provided by the Help System enable you to compile and view run-time help files by clicking a help file icon or choosing a menu item. However, if you want to select particular command options, you must enter the command manually in a terminal window or create new actions.
Help actions and data types are defined in two files, dthelp.dt and dthelptag.dt , located in the /usr/dt/appconfig/types/ lang directory.
The commands summarized here are:
- dthelptag
- Compiles HelpTag source files into a run-time file.
dthelpview - Displays a help volume, help topic, text file, or man page.
- dthelpgenCollects help family files into a new help volume,
browser.hv , which contains an entry for each family file.
The HelpTag software, invoked with the dthelptag command, compiles your HelpTag source files into a run-time help file. You run dthelptag in the directory where your volume.htg file is located.
Command Syntax
dthelptag [command-options] volume [parser-options]
Where command-options are options entered before the volume name and parser-options are options entered after the volume name.
Command Options
- -cleanRemoves all files generated from any previous run of HelpTag for the given volume.
- -shortnamesCauses the names of all generated files to be limited to a maximum of eight characters for the base name and three characters for the extension. This allows run-time help files to be moved to systems where longer names may not be supported.
- -verboseDisplays the progress of the dthelptag command and displays any parser errors that occur. Parser errors are also saved in a file named volume.err.
-formal - Uses the formal parser to interpret help files tagged with
SGML-compliant markup. If not specified, dthelptag assumes the input file contains shorthand markup.
Because there are two types of markup--shorthand and formal--it is recommended to distinguish the types by using a file extension. Use.htg for shorthand markup and use.ctg for formal markup.
Parser options, which are entered after the volume name, are passed directly to the parser, which is the part of the HelpTag software that converts your marked-up files into a run-time file.
These options can be applied in the following ways:
- Entered on the command line after the volume name
- Listed in a file named helptag.opt located in the current directory
- Listed in a file named volume.
opt in the current directory
- Set using the
DTTAGOPT environment variable
Options entered on the command line override those options that may have also been set using a different method.
- onerror
- Specifies whether the dthelptag command should continue if a parser error is encountered. The default is onerror=stop, which causes the command to stop even if one parser error is encountered. If you specify onerror=go, processing will continue, but the created run-time help file may not work properly.
- charsetSpecifies which character set was used to author the text files. The correct character set name is needed to ensure that the help topics are displayed in the proper font. The default is charset=ISO-8859-1. You can also specify a character set within your help volume by declaring an entity named
LanguageElementDefaultCharset . The /usr/dt/dthelp/dthelptag/helplang.ent file includes this entity declaration. See Chapter 14, "Native Language Support,"for a list of supported character sets.
- search
- Adds another directory to the list of directories that are searched to find referenced file entities. To specify multiple directories, use multiple search=directory options. If no search options are used, only the current directory is searched.
- clearsearchIgnores the list of search directories. This option is useful in the command line to override search options specified in the helptag.opt file.
- memo
- Causes author's memos (which are entered using the <memo> element) to be included. The default is nomemo, which causes HelpTag to ignore memos.
- nomemo
- Causes HelpTag to ignore author's memos (which are entered with the <memo> element). This is the default.
See Also
The dthelpview command can be used to display a help volume, individual help topic, text file, or man page.
Command Syntax
The various ways to invoke Helpview are:
- dthelpview -helpVolume volume [ -locationId id ]
- dthelpview -man
- dthelpview -manPage man
- dthelpview -file filename
Where:
- -helpVolume volume
- Specifies the name of the volume.sdl file you want to view. A path name is not required unless the volume is not in the current directory and the volume has not been registered.
- -locationId id
- Specifies an ID.
dthelpview displays the topic that contains id. If you do not specify an ID, Helpview uses _hometopic by default.
- -manDisplays a dialog that prompts for a man page to view, then displays the requested man page.
- -manPage man
- Specifies that a particular man page be displayed.
- -file filename
- Specifies that a particular text file be displayed.
The default volume and id can be set in dthelpview's app-defaults file, /usr/dt/app-defaults/C/Dthelpview.
See Also
The dthelpgen utility creates a special help volume that enables users to display help volumes registered on their system using the Front Panel Help Viewer. When a user initially clicks the Help Viewer control in the Front Panel, dthelpgen is run automatically. It locates help family files by searching the help search path directories (local or networked), and then creates a browser volume (browser.hv ) in the user's HomeDirectory/.dt/help/$DTUSERSESSION directory. Once built, the volume is updated in response to any of these actions:
- Add, remove, or modify family files or help volumes
- Change the LANG environment variable
- Invoke the ReloadApps action
- Run
dthelpgen manually in a terminal window
The browser volume is displayed by clicking the Help Viewer control in the Front Panel. Or, you can manually run dthelpview and supply the browser volume name as shown in this command line:
dthelpview -h browser.hv
Command Syntax
dthelpgen -dir [options]
Where:
- -dirSpecifies the directory in which to place the browser volume and intermediate files. This is a required parameter.
Options
- -generate
- Specifies that a new browser help volume should be created even if the family files and help volumes on the system have not been modified.
- -file basename
- Specifies the name of the help volume and any intermediate files generated by
dthelpgen . The default name is browser.hv .
- -lang
- Specifies which language directories to search for help families and help volumes. If the -lang option is set, it takes precedence over the current value of the LANG environment variable.
Note: If you run dthelpgen while the browser volume is displayed in a help window, you should close the window, then reopen the browser volume.
See Also
|