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 chapter explains which options and switches you can pass to hsc, and which exit codes it might return to the shell. For easier understanding, related options are collected in groups.

Although for most descriptions there are short examples available, this is intended to be a reference only. For several options, you can find more detailed explanations in other sections of this manual.

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 wants a decimal number. If an invalid number is specified, an error will be returned.
/A - Required. (think: ``Always''!)
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.

Exit Code

The exit-code hsc returns to the shell 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.

Specifying Input and Output

FROM/M
Specifies the input filename. To use stdin as input file, the pseudo filename STDIN (case sensitive) should be specified, or alternatively the unixoid ``-''. 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.

Message Options

IGNORE=IGN/K/M
Ignore message number or class. Usually, IGNORE needs a numeric argument and can occur multiple times in the command line. Additionally, you can specify some special values, which will ignore whole groups of messages: ALL, NOTE, STYLE, PORTABILITY and JERK. See Ignore/Enable Certain Messages and Classes for more information.
ENABLE=ENA/K/M
This is the opposite to IGNORE and can be used to enable certain messages. You can also use the same special values as with IGNORE. See Ignore/Enable Certain Messages and Classes for more information.
MSGMODE/K
Set base mode for syntax check. Legal values are PEDANTIC, NORMAL and RELAXED. Default is NORMAL. See Ignore/Enable Certain Messages and Classes for more information.
MSGFILE/K
Redirects messages to a file. By default, stderr is used. See Redirecting Messages and Changing the Message Format for more information.
MSGFORMAT/K
Describes how messages should be displayed. See Redirecting Messages and Changing the Message Format for more information.
NONESTERR/S
Suppresses the ``location of last call'' messages that usually provide a ``traceback'' when errors/warnings are displayed. If you use deeply nested macros, these confuse more than they clarify, so you can use this switch to see only the place where an error was detected.
NOVALIDATECSS=NVCS/S
Disables the checking of CSS style specifications. See CSS support for further information. In XHTML mode, CSS checking cannot be disabled, trying this will yield a warning.

Configuration

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"
INCLUDEDIR=IDIR/K/M
By default, only the current directory and the main source's directory are scanned for files to be included (using the commandline option From or the special tags <$include> or <$exec>). This option adds a directory to the list of directories to search for include files.
PREFSFILE/K
Specifies the filename for a syntax definition to be used, in case you don't want to use the default.
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.
SERVERDIR/K
This option tells hsc where to look for files referenced by server-relative URIs. The directory has to be specified as a native filename of your OS. Example: SERVERDIR=aws:home might work fine under AmigaOS, SERVERDIR=/home/sepp/public_html could be used on a unixoid system.
CHECKEXTERNAL=CKX/S
In times of ``always on'' internet connections it may seem a little anachronistic to check only local URIs for existence. Using this switch, you can enable external URI checking for HTTP, so hsc will actually ask the remote server for any document you reference. This can and will tremendously slow it down, but for a final run before upload it can be worth the time.
So far, hsc only speaks HTTP. However, proxies are supported via the the same environment variables as in Lynx: http_proxy, ftp_proxy and gopher_proxy. So if you can use a proxy, you can even check URIs of the latter types.

Options Affecting The Output

GETSIZE/S
Get width and height of images and set corresponding attributes WIDTH and HEIGHT (or the appropriate CSS attributes within a STYLE attribute when running in XHTML mode) with these values.
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.png" ALT="back">. Note that this argument does not denote a directory but an URI. It is recommended to use a Project Relative URI.
QUOTESTYLE/K
Specifies which kind of quotes should be used to surround attribute-values. KEEP keeps the kind found in the source, DOUBLE tries to assign double quotes (eg. "value"), SINGLE tries to assign single quotes (eg. 'value') and NONE will remove quotes if possible.
In XHTML mode, only double quotes are permitted. DOUBLE is also the default in old-style HTML mode.
ENTITYSTYLE/K
Sets the rendering of entities either found in the source or generated using RPLCENT. The following styles are possible:
KEEP
Keep entities as they were found in the source. If entities were generated from hi-ASCII characters (see RPLCENT), they will be in the symbolic form, unless their entity definition says otherwise.
REPLACE
Replace entities with the form their definition says is preferred.
NUMERIC
Always render entities numerically.
SYMBOLIC
Always render entities symbolically (if a symbol exists—numerically otherwise).
UTF-8
Don't write HTML entities at all, except for ``&lt;'', ``&gt;'', ``&quot;'' and ``&amp;'', but write UTF-8 text. This applies to both entities found in the source and replacements for hi-ASCII characters. You must declare the UTF-8 charset in a META tag, otherwise most browsers would assume it to be Latin-1 and render it incorrectly. UTF-8 mode is the default for XHTML,
To let you react on the entity style currently used in conditionals, hsc defines the Hsc.Opts.Entitystyle variable.
RPLCENT/S
Replace special characters with their entities. For instance, ``ü'' turns into ``&uuml''. Also see ENTITYSTYLE!
RPLCQUOTE/S
Replace double quotes (``"'') found in the text by ``&quot;''. This does not affect quotes used inside attribute values.
LOWERCASETAGS=LCT/S
There are many different conventions for tag case that people find convenient, and as it didn't matter for HTML, that was fine. For XML it does. Even if you are not writing XHTML, you can force your tags and attributes to lowercase with this switch and keep your tagging idiom and your old macro files as they are.
XHTML/S
XHTML introduces some new conventions that are incompatible with HSC's usual opinion about correct HTML:
  • Boolean attributes must not be minimized. I.e. it's <hugo resi="resi"> now, instead of <hugo resi>.
  • Empty tags may (and, to reduce bogosity and waste of bandwidth, should) be minimized to a form like <hugo/>, or, to stay compatible with older HTML browsers, <hugo /> (note the space!). With the trailing-slash-recognition being a bit of a hack, HSC supports only the latter form, i.e. with space.
  • All tags and attributes must be lowercase.
There are probably other criteria that I forgot, but this is what HSC enforces so far if you set this switch.

Stripping Data From The Output

COMPACT/S
Strip redundant linefeeds and white-spaces from output.
STRIPBADWS/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.
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.

Miscellaneous Options

HELP=?=-h=--help/S
Display a short help message and exit.
LICENSE/S
Display a short version of the GNU General Public License and exit.
-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.
STATUS/K
Display several status messages (output goes to stderr). Legal flags are:
  • QUIET: no status messages
  • LINE: display name and line of file currently processing. Names of files included are also displayed. After processing a file, the filename and the total number of lines remain visible.
  • VERSION: display program title and version
  • VERBOSE: enable verbose status messages; this includes the information displayed during the processing of <$exec> and some details about images, if GetSize has also been enabled.
  • FULL: enable all status messages
The above flags can be combined by separating them with a vertical bar (``|''), eg "STATUS=line|version", except for QUIET and FULL