help(4) help(4)
NAME
help - Desktop help file format
DESCRIPTION
The help system can display plain help files as well as
formatted help files. To use the hypertext functionality,
help files must conform to the format described in this
section. Each help file must have a file header and one or
more section headers, depending on the number of sections in
the file.
Format Header Definition
The file header contains information that is global to the
file and must appear before the start of the first section of
text. Each line in the file header begins with the ^
character. The following are the control codes and line
formats allowed in the file header:
^*version^n
This must be the first line in the file header. The
rest of the file will be parsed according to the version
specified. n must be 1. Other values of n are reserved
to support other formats in the future.
Example:
^*version^1
^*width^n
This specifies the maximum width of the help window's
text pane in units of characters. If you do not specify
a width, the system defaults to 70 characters.
Example:
^*width^75
^+definition_file
This specifies the name of a file containing only a
glossary of terms. Each definition is defined using the
^= option. Definitions can also appear in the file
header itself.
Example:
^+DesktopMgr/help.defs
Copyright 1994 Novell, Inc. Page 1
help(4) help(4)
^?description
This is a one-line description of the application or
object that you are writing the help for. It is
displayed when the user double-clicks on the icon that
represents the application or object in the "Help Desk"
window.
Example:
^?Overview of the Help Desk
^*title^string
This specifies the title used in the help window title,
unless you specify a section name or a title in the
request to display help.
Example:
^*title^Help Desk
^=icon_label
This specifies the icon label that will be used in the
"Help Desk" window.
Example:
^:Help_Desk
^%keyword^reference
This is a keyword definition which is global to the
file. Each occurrence of keyword in the file is
highlighted in color. When the user selects the
keyword, the text in the help window's pane area will be
switched to the text which the reference points to.
The reference has the format file_name^section_tag,
where file_name is the name of a help file, section_tag
is either a section name or a section tag associated
with a section in the help file. A tag is any ASCII
string and can be used across different locales.
file_name defaults to the current file. section_tag
defaults to the first section of a file if it is not
specified.
Copyright 1994 Novell, Inc. Page 2
help(4) help(4)
Example:
^%right-click^MENU
^=term\ndefinition\n^=
This is a definition of a term and is global to the
file. Each occurrence of term in the file is displayed
in italics font. When a term is selected, a window pops
up to display the definition of the term.The definition
can comprise multiple lines.
Example:
^=double-click\ndouble-click\n^=
Section Header Definitions
A section definition contains a section header followed by
help text. A section header begins with a line of the format
^level^section_name^alias. Following this line may be a
section tag, and, optionally, local definitions of terms and
keywords. These local definitions override any previous
definitions of the same terms or keywords. The same options
are used to define local and global terms and keywords. The
rest is considered the body of the section until the end of
file is reached or another section is defined.
^level^section_name[=alias]
This is used to specify a section number, a section
name, and an optional alias to the section_name. The
level starts at 0 and must be a positive integer. If
you specify a level of 0, the section appears in the
Table of Contents and the help window pane without a
level number. This is to allow having a main section in
a file. A level 0 section is optional. A section
typically starts at level 1. The maximum level of
sections allowed is six. Sections beyond the sixth
level will not be displayed in the Table of Contents.
section_name is used internally by the Desktop Manager
and appears in the Table of Contents, but does not
automatically appear at the beginning of a section. If
you want the section name repeated at the start of a
section, you must enter the section name on a line by
itself at the beginning of the help text.
Copyright 1994 Novell, Inc. Page 3
help(4) help(4)
alias is optional. If you specify an alias, the system
uses it to look up a link. Otherwise, the system uses
section_name. This allows a file to have more than one
section with the same name and multiple keywords which
are the same but linked to different parts of the file.
This is useful if section tags are not available at the
time keywords are defined, which may be the case if a
tool is used to create the keywords. alias is never
displayed.
Example:
^0^Overview of the Help Desk
^$tag You can define a unique section tag for each section
within a section header. Since section tags are unique,
you can use them to link the same keyword to different
sections in a file. A tag can be any ASCII string and
can be used across locales. Section tags should be used
to differentiate multiple sections having the same
section_name. Otherwise, backtracking might not give
the expected section.
Links
The following constructs are used within the help text to mark
defined terms and hypertext links.
\d(term[,alias])
This indicates that the string term is to be displayed
in italics. If you do not specify alias, the system
displays the definition of term in a definition pop-up
window. Otherwise, the system displays the definition of
alias in the definition window. alias allows multiple
terms to share the same definition.
Example:
\d(active icon [,icon])
Definitions are defined using the ^= option in a
definition file, file or section header.
\k(keyword[^reference])
This is used to indicate and set up a link within a
section. keyword appears as part of the section. When
a user selects a keyword, reference looks up which file
Copyright 1994 Novell, Inc. Page 4
help(4) help(4)
and section to jump to.
You must format reference in the format file
name^section_name/tag, and you must specify, minimally,
either the file name or section_name/tag. The section
associated with section tag in file name displays in the
help window when the user selects the keyword.
reference allows the same keyword to be associated with
the different sections in the same or a different file.
If you do not specify reference, keyword looks up a
link, which can be a link defined in the section or file
header.
Example:
\k(Saving Text^dtedit/edit.hlp^Saving Text)
In this example, the user clicks on the highlighted text
"Saving Text." The system searches for the section
"Saving Text" in dtedit/edit.hlp and displays the help
associated with that section.
Note that if you use parentheses within the definition
of a link, the link itself must be enclosed with curly
braces instead of parentheses, and vice-versa, as
follows:
Example:
\k{cat(1)}
\k{cat^cat(1)}
The definition of a term or a link must not contain any
newline (\n) character.
EXAMPLE
#ident"%W%"
^*version^1
^*title^Message Monitor
^:Msg_Monitor
^*width^70
^+DesktopMgr/help.defs
^?Displaying system messages
^0^Message Monitor
Copyright 1994 Novell, Inc. Page 5
help(4) help(4)
^$10
Message Monitor
Use the Message Monitor to view messages from the operating system that you
cannot easily view while the Desktop is running.
The Message Monitor displays messages that UnixWare sends to the messaging
device (/dev/osm). This device, which normally receives messages from
UnixWare, receives most messages that are also sent to the system console.
You can do the following with Message Monitor:
o \k(View system messages^^Viewing System Messages)
o \k(Save system messages^^Saving System Messages)
^1^Viewing System Messages
^$20
Viewing System Messages
To view system messages, do the following:
Note: If you are already in the Applications folder, go to Step 2.
1. \d(Double-click^double-click) on Applications in the "UnixWare Desktop"
window. The "Folder: Applications" window appears.
2. Double-click on Msg_Monitor. The "Message Monitor" window appears.
3. Use the scroll bar to move up and down through the list of messages.
Note: To clear, or remove, all messages from this window, click on
View=>Clear.
See also:
\k(Saving System Messages)
^1^Saving System Messages
^$30
Saving System Messages
To save the messages in Message Monitor, do the following:
Note: If you are already in the Applications folder, go to Step 2.
1. \d(Double-click^double-click) on Applications in the "UnixWare Desktop"
Copyright 1994 Novell, Inc. Page 6
help(4) help(4)
window. The "Folder: Applications" window appears.
2. Double-click on Msg_Monitor. The "Message Monitor" window appears.
3. Click on one of the following:
o File=>Save - To save the messages to an existing file.
o File=>Save As - To save the message to a file other than the default
file. Type in the desired path and click OK.
o File=>Append To - To copy the messages to the end of the existing
default file.
If you are saving system messages for the first time, the "Save"
window appears. Type in the desired path and click OK.
Copyright 1994 Novell, Inc. Page 7