makehelp(1) — Commands
NAME
makehelp — VUE Help File creation utility.
SYNOPSIS
makehelp [-v file] filename
DESCRIPTION
The VUE Help File creation utility is a ksh(1) script with nawk(1) commands. It provides an easy mechanism for changing human readable files into a catalogue file suitable for use by the VUE Help Manager (vuehelp(1)).
OPTIONS
−v file This option specifies the file to use for creating a what string for the resultant catalogue file. If file contains a string that can be processed by strings(1) and has the "@(#)" what string indicator, this string is placed in set 99 message 1 of the catalogue file. Additionally, if the resultant string has the word "FILE_VERSION", it will be replaced with the revision string found in filename.
filename
This is the name of the file to process. If it has an extension, the base name plus the extensions, ".msg" and ".cat", will be created. If one or more widget paths are specified (explained in more detail below), the base name plus the extension ".hlp" will also be created.
makehelp File Syntax
makehelp processing is based on tokens. A token is the first non-blank set of 1 or more characters followed by one or more blanks. Therefore, a question mark as the first character on a line is the same as a line with five blanks followed by a question mark.
If the following characters are the first token on a line, makehelp will process them according to the associated rules. If the developer/writer wishes to use the special character as the first token on a line but does not want the rule invoked, put a backslash in front of the special character.
% glossaryfile
This is used to specify the glossary to associate with this file. The second token on the line must be a filename. If the filename is /<path>/<file>, the Help manager assumes the file is /usr/lib/X11/vue/help/<lang>/<path>/<file>.cat. If the filename is <path>/<file>, the Help Manager assumes the file is /usr/lib/X11/vue/help/<lang>/tools/<path>/<file>.cat. If the filename does not contain slashes, the Help Manager assumes the glossary file is /usr/lib/X11/vue/help/<lang>/gloss/<file>.cat. The Help Manager will show this glossary whenever this file is being viewed and the Glossary View option is in effect for the Help Viewer.
? widgetpath<:;> title
The question mark determines the beginning of a topic. The second token on the line must be question mark or a widget path. The third and subsequent tokens are taken as the title for the topic.
A widgetpath is the parent to child relationship of a widget within an application. Each widget within an application should have a name. For an example lets take an application, named App, that has a shell widget name ’Shell’ and it contains a form widget named ’Form’. The form widget contains a row column manager named ’RowColumn’ and a push button named ’Quit’. The row column widget contains two push buttons named ’Push’ and ’Pull’. The widgetpath for the push button named ’Push’ would be App.Shell.Form.RowColumn.Push. The widgetpath for the push button named ’Quit’ would be App.Shell.Form.Quit.
The widgetpath used as the second token for the topic can be a fully qualified widget path, as in the example above, or stars (∗) can be substituted for unimportant parts of the path. For example, we had two buttons that were named ’Quit’ and they had the same functionality but they had different widget paths, i.e App.Shell.Form.Quit and App.Shell.Form.RowColumn.Quit. In this case when context sensitive help is requested, the same message should be given for each. For this case, the widgetpath give for this topic could be App∗Quit.
Now, if we had a third button name ’Quit’ but it has a different functionality than the other two buttons named ’Quit’, we would have to qualify the first two buttons further to prevent the third button from using the incorrect topic.
Each widgetpath is ended with a colon or semi-colon. If a colon is specified, the string ’∗help’ is appended to the widgetpath. If a semi-colon is specified, the string ’.help’ is appended. This gives the documentation writer another level of qualification on the widgetpath. If two items are labeled ’Quit’ and have the same functionality, but ’Quit’ is in the middle of a widgetpath and at the end in another, by placing a colon on the end of the widgetpath ’App∗Quit’ the makehelp will expand it to ’App∗Quit∗help’. When the application sends the widgetpath (via the Help API) to the Help Manager, a ’.help’ is appended onto it. Therefore, if the widget path is ’App.Form.Quit.Label’ it will become ’App.Form.Quit.Label.help’ and ’App∗Quit∗help’ will match. If the widget path is ’App.Form.RowColumn.Quit’, it will become ’App.Form.RowColumn.Quit.help’ and it too will match. If a semi-colon had been used instead of a colon, ’App∗Quit’ would have been expanded by makehelp to ’App∗Quit.help’. ’App.Form.RowColumn.Quit.help’ would match but ’App.Form.Quit.Label.help’ would not.
By using stars instead of dots and colons instead of semi-colons, the documentation writer can reduce the sensitivity of the context sensitive help messages. The more specific the widget path (using dots and semi-colon) the fewer items in the application will match a widgetpath for context sensitive help.
The application vuepath will show an application’s widgetpaths if the application has attached the Help API and allows context sensitive help on the application. See vuepath(1) for more information.
+ widgetpath<:,;>
The plus sign specifies that widgetpath<:,;> is to be associated with this topic. In this way, more than one widgetpath can be declared for each topic. Each widget path must end with a colon or semi-colon just as it did for the title specification. Using this token, widgetpaths can be specified on individual lines or grouped together on multiple lines.
# words The pound sign is considered a comment line. This allows the developer/writer to internally document the source file. All lines starting with # are ignored for the creation of the catalogue file.
! tag_string
The exclamation mark (or bang) specifies a tag string entry for this topic. The second token on the line is the ’name’ or ’tag string’ for this topic in this file. This allows other topics in the same file or different files to access this topic via cross referencing and related topics. If a tag string is not declared for the topic, ’none’ is assumed and no cross referencing or related topics can use this entry.
@ filename:tag_string
The at sign specifies a cross reference. It is used to access a common definition for an item. For example, an application uses scrollbars and another file has a very good description of scrollbars. Rather than copy or retype the text into the new file, the developer/writer will use cross referencing to access the text in another file. The second token of a cross reference must be in the format filename:tag_string.
filename is optional. If filename is absent, the Help Manager assumes tag_string references into this file. If filename is /<path>/<file>, the Help Manager assumes the file that contains <tag_string> is /usr/lib/X11/vue/help/<lang>/<path>/<file>.cat. If <filename> is <path>/<file>, the Help Manager assumes the file that contains <tag_string> is /usr/lib/X11/vue/help/<lang>/tools/<path>/<file>.cat. If <filename> does not contain a slash, the Help Manager assumes the file that contains <tag_string> is in the same directory as this file. When the information about this topic is accessed, the text used will be from the topic that has tag_string as its ’name’ in the file filename.
Cross references and text can be intermixed. In this manner, pieces of text referenced by cross references can be placed in between lines of regular text.
Note: Only one level of cross referencing is allowed. A cross reference can not access a topic whose message contains a cross reference.
& filename:tag_string
The ampersand is used to create related topic references. The second and subsequent tokens must be in the format filename:tag_string. filename is optional. If filename is absent, the Help Manager assumes tag_string references into this file. If filename is /<path>/<file>, the Help Manager assumes the file that contains <tag_string> is /usr/lib/X11/vue/help/<lang>/<path>/<file>.cat. If <filename> is <path>/<file>, the Help Manager assumes the file that contains <tag_string> is /usr/lib/X11/vue/help/<lang>/tools/<path>/<file>.cat. If <filename> does not contain a slash, the Help Manager assumes the file that contains <tag_string> is in the same directory as this file.
Related topics can be listed on separate lines or grouped together on a line. The related topics can be grouped as long as each specification is separated by one or more blanks. The related topics’ titles will be shown in the Help Viewer’s See Also window when this file is viewed.
message text
Any other line is considered a message line. This is the information shown in the Help Viewer when information about a topic is requested. As noted above, cross references can be used instead or intermixed with regular text.
COPYRIGHT
(c) Copyright 1989 by Hewlett-Packard Company
All rights reserved.