Main ----- Copyright Up Previous Next

shoulder, bicep, elbow, arm
forearm, thumb, wrist, knuckle, palm
middle, pinky, index, ring
dinner bell dinner bell ding
(They Might Be Giants, "Dinner Bell")

Invoking hsc

This section covers which options and switches you can pass to hsc, and which exit codes are returned to CLI.

General rules for options

As hsc is an tool developed under AmigaOS and I never liked the cryptic "cmd -cvf -osepp.x"-way of invoking commands coming from Unix, hsc uses a syntax like most commands of AmigaOS; even for ports on other operating-systems. (Technical note: AmigaOS provides an OS-function called ReadArgs() for argument-parsing.)

All options and switches are case-insensitive. If you start hsc without any options, a short help message will be displayed.

Options can be followed by modifiers, which specify things such as the type of the option. Modifiers are specified by following the option with a '/' and a single character modifier. Multiple modifiers can be specified by using multiple '/'s. Valid modifiers are:

/S - Switch.
This is considered a boolean variable, and will be set if the option name appears in the command-line.
/K - Keyword.
This means that the option will not be filled unless the keyword appears. For example if the template is ``Name/K'', then unless ``Name={string}'' or ``Name {string}'' appears in the command line, Name will not be filled.
/N - Number.
This parameter is considered a decimal number. If an invalid number is specified, an error will be returned.
/A - Required.
This keyword must be given a value during command-line processing, or an error is returned.
/M - Multiple strings.
This means the argument will take any number strings. Any arguments not considered to be part of another option will be added to this option.

Options

FROM/M
Specifies the input filename. To use stdin as input file, the pseudo filename STDIN (case sensitive) should be specified. If you specify more than one file, the last file is taken as main source, and all previous files are included before it. This is useful to include macro-definitions within the command-line instead of an <$include> in the hsc-source.
TO/K
Specifies the output filename or the destination directory. If the argument ends with a "/" (or also ":"), it is interpreted as a directory. In this case, the name of the output file is created from the name of the input file, with an extension specified (see below). If no output file is set, stdout is used instead.
For details, read the section about File Options
EXTENSION/K
If you specify a directory for output, the output-filename will depend on the input-filename and the extension specified with this options. If you do not set an extension, "html" will be used. A period (``.'') will be added automatically. Setting EXTENSION=. will omit this and result into exactly the same filename as the input. If you specify a complete filename for output, this option has no effect.
MSGFILE/K
Redirects messages to a file. By default, stderr ist used.
MSGFORMAT/K
Describes how messages should be displayed. Conversion specifications: 
        %f      filename
        %x, %y  location in file (column, line)
        %c      message class
        %i      message id (numeric)
        %m      message text
        %n      inserts a linefeed
Example: To get GCC-like messages, use MSGFORMAT="%f:%y: %c %i: %m".
PREFSFILE/K
Specifies filename for sytax-definition to be used, if you don't want to use the defaults.
PRJFILE/K
Stores some information about the document currently processing in a seperate file to extend functionality. Read the section about Project management for more details. Note that all documents within a project should use the same project-file.
DEFINE=DEF/K/M
Defines a global attribute. The syntax is equal to <$define>, exept that you need no quotes surrounding the value.
Example: DEFINE "hugo:string=hugo was here"
IGNORE=IGN/K/M
Ignore warning message number. Usually, IGNORE needs a numeric argument and can occur multiple. Example:
IGNORE=21 IGN=18 IGN 3 (ignore warnings #21, #18, #3)
Additionally, you can specify some special values, which will ignore whole groupss of messages: These values add new messages to the list of messages to be ignored, but do not reset any IGNOREs passed before.
MODE/K
Set base mode for syntax check. Legal values are PEDANTIC, NORMAL and RELAXED. Default is NORMAL. This only disables several messages and warnings from the beginning. Any IGNOREs passed before are reseted.
QUOTESTYLE/K
Specifies which kind of quotes should be used to surround attribute-values. KEEP keeps the user-kind, DOUBLE tries to assign double quotes (eg. "value"), SINGLE tries to assign single quotes (eg. 'value') and NONE will remove quotes if possible.
INCLUDEDIR=IDIR/K/M
By default, only the current directory is scanned for files to be included (using the CLI option FROM or the special tags <$include> or <$exec>). This option adds a directory to the list of directories to search for include files.
STATUS/K
Display several status messages (output goes to stderr). Legal flags are: The above flags can be combined by separating them with a vertical bar (``|''), eg STATUS=line|version, except for QUIET and FULL
STRIPTAGS/K
Strip some specific tags from document. You can specify a list of tags which is a string, that contains all tags that should be stripped, separated by a vertical bar (``|'').
See also STRIPCOMMENT and STRIPEXTERNAL.
ICONBASE/K
Replace all icon entities by images that must be available from the base URI specified. If this URI contains an asterisk (``*''), it will be substituted by the icon name. For example, with ICONBASE=:icons/*.gif, the entity &back; is replaced by <IMG SRC=":icons/back.gif" ALT="back">. Note that this argument does not denote a directory, but an URI. It's recommended to use an absolute URI.
SERVERDIR/K
With this you can tell hsc where it should look for files referenced with a server relative URI. The directory has to be specified as a native filename of your OS. Example: SERVERDIR=aws:home might work fine under AmigaOS, SERVERDIR=/user/sepp/public_html could be used on an Unixoid system.

Switches

HELP/S
Display a short help message and exit.
LICENSE/S
Display a short version of the GNU General Public License and exit.
COMPACT/S
Strip redundant linefeeds and white-spaces from output.
-DEBUG/S
If you've compiled hsc in debug-mode, it will send lots of information to stderr. Otherwise, this option is equivalent to STATUS=FULL.
GETSIZE/S
Get width and height of images and set corresponding attributes WIDTH and HEIGHT with these values;
MSGANSI/S
Uses ANSI-sequences to make messages more readable. This option is recommended to be used by people who are not smart enough to integrate hsc in some of the existing project-management environments.
RPLCENT/S
Replace special characters with their entities (eg ``ü'' becomes ``&uuml'').
RPLCQUOTE/S
Replace double-quotes (``"'') found in the text by ``&quot;''. This does not affect quotes used inside attribute-values.
SMARTENT/S
Replace special characters ``&'', ``<'' and ``>'' with their entities (&amp;, &lt; and &gt;) if they are surrounded by white-spaces.
STRIPBASWS/S
Strip bad white spaces that would have caused message #78 or message #79; this will not strip those which cause message #47. The main advantage of this switch is that it allows you to write well structured macros.
STRIPCOMMENT/S
Strip all SGML-comments from input.
STRIPEXTERNAL/S
Strip tags which refer to an external URI.

Exit Code

The exit-code hsc returns to the CLI depends on the messages and errors that have been displayed during runtime.

The version for AmigaOS returns

For other systems, values like 0/0/1/2 are used instead.