/usr/share/doc/hsc/docs/options.html is in hsc 0.934-1ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>hsc - Invoking Hsc</title>
<link rev="owns" title="Thomas Aglassinger" href="mailto:agi@giga.or.at">
<link rel="Next" href="examples.html">
<link rel="Copyright" href="copy.html">
<link rel="Previous" href="install.html">
<meta name="ROBOTS" content="NOINDEX, NOFOLLOW">
</head>
<body>
<a href="index.html"><img src="image/main.png" alt="Contents" align="middle" width="70" height="16"></a>
<img src="image/noindex.png" alt="-----" align="middle" width="70" height="16">
<a href="copy.html"><img src="image/copy.png" alt="Copyright" align="middle" width="70" height="16"></a>
<a href="index.html"><img src="image/back.png" alt="Up" align="middle" width="70" height="16"></a>
<a href="install.html"><img src="image/prev.png" alt="Previous" align="middle" width="70" height="16"></a>
<a href="examples.html"><img src="image/next.png" alt="Next" align="middle" width="70" height="16"></a>
<hr>
<p align="right"><i>shoulder, bicep, elbow, arm<br>forearm, thumb, wrist, knuckle, palm<br>middle, pinky, index, ring<br>dinner bell dinner bell ding</i><br>
(They Might Be Giants, "Dinner Bell")
</p>
<h1>Invoking Hsc</h1>
This chapter explains which options and switches you can pass to
<kbd>hsc</kbd>, and which <a href="#exitcodes">exit codes</a> it might return
to the shell. For easier understanding, related options are collected in
groups.
<p>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.</p>
<h2><a name="general.rules">General Rules For Options</a></h2>
<p>As <kbd>hsc</kbd> is an tool developed under AmigaOS and I never liked
the cryptic "<kbd>cmd -cvf -osepp.x</kbd>"-way of invoking commands coming
from Unix, <kbd>hsc</kbd> uses a syntax like most commands of AmigaOS;
even for ports on other operating-systems. (<strong>Technical note</strong>: AmigaOS provides
an OS-function called <code>ReadArgs()</code> for
argument-parsing.)</p>
<p>All options and switches are case-insensitive. If you start <kbd>hsc</kbd>
without any options, a short help message will be displayed.</p>
<p>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:</p>
<dl>
<dt><kbd>/S</kbd> - Switch.
<dd>This is considered a boolean variable, and will be
set if the option name appears in the command-line.
<dt><kbd>/K</kbd> - Keyword.
<dd>This means that the option will not be filled unless
the keyword appears. For example if the template is
``<kbd>Name/K</kbd>'',
then unless ``<kbd>Name={string}</kbd>''
or ``<kbd>Name {string}</kbd>'' appears in the
command line, Name will not be filled.
<dt><kbd>/N</kbd> - Number.
<dd>This parameter wants a decimal number.
If an invalid number is specified, an error will be returned.
<dt><kbd>/A</kbd> - Required. (think: ``Always''!)
<dd>This keyword must be given a value during command-line
processing, or an error is returned.
<dt><kbd>/M</kbd> - Multiple strings.
<dd>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.
</dl>
<h2><a name="exitcodes">Exit Code</a></h2>
<p>The exit-code <kbd>hsc</kbd> returns to the shell depends on the messages and errors
that have been displayed during runtime.</p>
<p>The version for AmigaOS returns
<ul>
<li><code>0</code> on success,
<li><code>5</code> if warnings occurred,
<li><code>10</code> if errors showed up (also for errors in arguments) and
<li><code>20</code> if fatal errors happened (also for out-of-resources).
</ul>
For other systems, values like <code>0/0/1/2</code> are used instead.
<h2>Specifying Input and Output</h2>
<dl>
<dt><a name="from"><kbd>FROM/M</kbd></a>
</dt><dd>
Specifies the input filename. To use <code>stdin</code> as
input file, the pseudo filename <code>STDIN</code> (case sensitive)
should be specified, or alternatively the unixoid ``<code>-</code>''.
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 <a href="features/spctags.html#include"><code><$include></code></a> in the hsc-source.
</dd>
<dt><a name="to"><kbd>TO/K</kbd></a>
</dt><dd>
Specifies the output filename or the destination directory.
If the argument ends with a "<kbd>/</kbd>" (or also "<kbd>:</kbd>"),
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, <code>stdout</code>
is used instead.<br>
For details, read the section about
<a href="fileargs.html">File Options</a>
</dd>
<dt><a name="extension"><kbd>EXTENSION/K</kbd></a>
</dt><dd>
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, ``<code>html</code>''
will be used. A period (``<code>.</code>'') will be added automatically.
Setting <kbd>EXTENSION=.</kbd> 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.
</dd>
</dl>
<h2>Message Options</h2>
<dl>
<dt><a name="ignore"><kbd>IGNORE=IGN/K/M</kbd></a>
</dt><dd>
Ignore message number or class. Usually, <kbd>IGNORE</kbd>
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: <kbd>ALL</kbd>, <kbd>NOTE</kbd>,
<kbd>STYLE</kbd>, <kbd>PORTABILITY</kbd> and <kbd>JERK</kbd>.
See <a href="messages.html#ignore">Ignore/Enable Certain Messages
and Classes</a> for more information.
</dd>
<dt><a name="enable"><kbd>ENABLE=ENA/K/M</kbd></a>
</dt><dd>
This is the opposite to <kbd>IGNORE</kbd> and can be used to
enable certain messages. You can also use the same special values
as with <kbd>IGNORE</kbd>.
See <a href="messages.html#ignore">Ignore/Enable Certain Messages
and Classes</a> for more information.
</dd>
<dt><a name="msgmode"><kbd>MSGMODE/K</kbd></a>
</dt><dd>
Set base mode for syntax check. Legal values are <kbd>PEDANTIC,
NORMAL</kbd> and <kbd>RELAXED</kbd>. Default is <kbd>NORMAL</kbd>.
See <a href="messages.html#ignore">Ignore/Enable Certain Messages
and Classes</a> for more information.
</dd>
<dt><a name="msgfile"><kbd>MSGFILE/K</kbd></a>
</dt><dd>
Redirects messages to a file. By default, <code>stderr</code> is used.
See <a href="messages.html#msgformat">Redirecting Messages and
Changing the Message Format</a> for more information.
</dd>
<dt><a name="msgformat"><kbd>MSGFORMAT/K</kbd></a>
</dt><dd>
Describes how messages should be displayed.
See <a href="messages.html#msgformat">Redirecting Messages and
Changing the Message Format</a> for more information.
</dd>
<dt><a name="nonesterr"><kbd>NONESTERR/S</kbd></a>
</dt><dd>
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.
</dd>
<dt><a name="nvcs"><kbd>NOVALIDATECSS=NVCS/S</kbd></a>
</dt><dd>
Disables the checking of CSS style specifications. See
<a href="features/css.html">CSS support</a> for further information.
In XHTML mode, CSS checking cannot be disabled, trying this will yield a warning.
</dd>
</dl>
<h2>Configuration</h2>
<dl>
<dt><a name="define"><kbd>DEFINE=DEF/K/M</kbd></a>
</dt><dd>
Defines a global attribute. The syntax is equal to <a href="features/spctags.html#define"><code><$define></code></a>, exept
that you need no quotes surrounding the value.<br>
Example: <kbd>DEFINE "hugo:string=hugo was here"</kbd>
</dd>
<dt><a name="includedir"><kbd>INCLUDEDIR=IDIR/K/M</kbd></a>
</dt><dd>
By default, only the current directory and the main source's directory
are scanned for files
to be included (using the commandline option <a href="options.html#from"><kbd>From</kbd></a> or the
special tags <a href="features/spctags.html#include"><code><$include></code></a> or <a href="features/exec.html"><code><$exec></code></a>). This option adds a
directory to the list of directories to search for include
files.
</dd>
<dt><a name="prefsfile"><kbd>PREFSFILE/K</kbd></a>
</dt><dd>
Specifies filename for <a href="features/prefs.html">sytax-definition</a>
to be used, if you don't want to use the defaults.
</dd>
<dt><a name="prjfile"><kbd>PRJFILE/K</kbd></a>
</dt><dd>
Stores some information about the document currently processing
in a seperate file to extend functionality. Read the section
about <a href="project/index.html">Project management</a> for more
details. Note that all documents within a project should use the
same project-file.
</dd>
<dt><a name="serverdir"><kbd>SERVERDIR/K</kbd></a>
</dt><dd>
With this you can tell <kbd>hsc</kbd> where it should look for files
referenced with a server relative URI. The directory has to be
specified as a <strong>native</strong> filename of your OS.
Example:
<kbd>SERVERDIR=aws:home</kbd> might work fine under AmigaOS,
<kbd>SERVERDIR=/user/sepp/public_html</kbd> could be used
on an Unixoid system.
</dd>
<dt><a name="checkexternal"><kbd>CHECKEXTERNAL=CKX/S</kbd></a>
</dt><dd>
In times of ``always-on'' internet connections it might seem a little
anachronistic to check only local URIs for existence. Using this switch, you
can enable external URI checking for HTTP, so <kbd>hsc</kbd> 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.<br>
So far, <kbd>hsc</kbd> only speaks HTTP. However, proxies are supported via the the
same <a href="envvar.html#http_proxy">environment variables</a> as in
<a href="http://lynx.browser.org/">Lynx</a>: <code>http_proxy</code>,
<code>ftp_proxy</code> and <code>gopher_proxy</code>. So if you can use a
proxy, you can even check URIs of the latter types.
</dd>
</dl>
<h2>Options Affecting The Output</h2>
<dl>
<dt><a name="getsize"><kbd>GETSIZE/S</kbd></a>
</dt><dd>
<a href="features/getsize.html">Get width and height of images</a>
and set corresponding attributes
<code>WIDTH</code> and <code>HEIGHT</code> with these values.
</dd>
<dt><a name="iconbase"><kbd>ICONBASE/K</kbd></a>
</dt><dd>
Replace all icon entities by images that must be available from
the base URI specified. If this URI contains an asterisk (``<code>*</code>''), it
will be substituted by the icon name. For
example, with <kbd>ICONBASE=:icons/*.gif</kbd>, the entity
<code>&back;</code>
is replaced by <code><IMG SRC=":icons/back.png" ALT="back"></code>. Note
that this argument does not denote a directory, but an URI. It's
recommended to use a <a href="features/uris.html#prjrel">Project Relative URI</a>.
</dd>
<dt><a name="quotestyle"><kbd>QUOTESTYLE/K</kbd></a>
</dt><dd>
Specifies which kind of quotes should be used to surround
attribute-values. <kbd>KEEP</kbd> keeps the kind found in the source,
<kbd>DOUBLE</kbd> tries to assign double quotes
(eg. <code>"value"</code>),
<kbd>SINGLE</kbd> tries to assign single quotes
(eg. <code>'value'</code>) and <kbd>NONE</kbd> will remove
quotes if possible.<br>
In XHTML mode, only double quotes are permitted. DOUBLE is also the default
unless something else is specified.
</dd>
<dt><a name="entitystyle"><kbd>ENTITYSTYLE/K</kbd></a>
</dt><dd>
Sets the rendering of entities either found in the source or generated using
<a href="#rplcent">RPLCENT</a>. The following styles are possible:
<dl>
<dt>KEEP</dt><dd>Keep entities as they were found in the source. If entities
were generated from hi-ASCII characters (see
<a href="#rplcent">RPLCENT</a>), they will be in the symbolic
form, unless their <a href="features/prefs.html#defent">entity
definition</a> says otherwise.</dd>
<dt>REPLACE</dt><dd>Replace entities with the form their definition says is
preferred.</dd>
<dt>NUMERIC</dt><dd>Always render entities numerically.</dd>
<dt>SYMBOLIC</dt><dd>Always render entities symbolically.</dd>
<dt>UTF-8</dt><dd>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.</dd>
</dl>
For automatic detection of the entity style currently used, <kbd>hsc</kbd> defines the
<code><a href="features/spcattr.html#opts-entitystyle">Hsc.Opts.Entitystyle</a></code>
variable.
</dd>
<dt><a name="rplcent"><kbd>RPLCENT/S</kbd></a>
</dt><dd>
<a href="features/rplcent.html">Replace special characters</a> with
their entities. For instance, ``<code>ü</code>'' turns into
``<code>&uuml</code>'').
</dd>
<dt><a name="rplcquote"><kbd>RPLCQUOTE/S</kbd></a>
</dt><dd>
Replace double-quotes (``<code>"</code>'') found in the text by
``<code>&quot;</code>''. This does not affect quotes used inside
attribute-values.
</dd>
<dt><a name="lowercasetags"><kbd>LOWERCASETAGS=LCT/S</kbd></a>
</dt><dd>
There are many different conventions for tag case that people find
convenient. 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.
</dd>
<dt><a name="xhtml"><kbd>XHTML/S</kbd></a>
</dt><dd>
XHTML introduces some new conventions that are incompatible with HSC's usual
opinion about correct HTML:
<ul compact>
<li>Boolean attributes must not be minimized. I.e. it's <code><hugo
resi="resi"></code>
now, instead of <code><hugo resi></code>.
<li>Empty tags may (and, to reduce bogosity and waste of bandwidth, should)
be minimized to a form like <code><hugo/></code>, or, to stay compatible
with older HTML browsers, <code><hugo /></code> (note the space!). With the
trailing-slash-recognition being a bit of a hack, HSC supports only the
latter form, i.e. <em>with</em> space.
<li>All tags and attributes must be lowercase.
</ul>
There are probably other criteria that I forgot, but this is what HSC
enforces so far if you set this switch.
</dd>
</dl>
<h2>Stripping Data From The Output</h2>
<dl>
<dt><a name="compact"><kbd>COMPACT/S</kbd></a>
</dt><dd>
<a href="features/strip.html">Strip redundant linefeeds
and white-spaces</a> from output.
</dd>
<dt><a name="stripbadws"><kbd>STRIPBADWS/S</kbd></a>
</dt><dd>
Strip bad white spaces that would have caused <a href="message-list.html#message.78">message #78</a>
or <a href="message-list.html#message.79">message #79</a>; this will not strip those which cause
<a href="message-list.html#message.47">message #47</a>. The main advantage of this switch is that
it allows you to write well structured macros.
</dd>
<dt><a name="stripcomment"><kbd>STRIPCOMMENT/S</kbd></a>
</dt><dd>
Strip all SGML-comments from input.
</dd>
<dt><a name="stripexternal"><kbd>STRIPEXTERNAL/S</kbd></a>
</dt><dd>
Strip tags which refer to an external URI.
</dd>
<dt><a name="striptags"><kbd>STRIPTAGS/K</kbd></a>
</dt><dd>
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 (``<code>|</code>'').<br>
See also <a href="options.html#stripcomment"><kbd>StripComment</kbd></a> and <a href="options.html#stripexternal"><kbd>StripExternal</kbd></a>.
</dd>
</dl>
<h2>Miscellaneous Options</h2>
<dl>
<dt><a name="help"><kbd>HELP=?=-h=--help/S</kbd></a>
</dt><dd>
Display a short help message and exit.
</dd>
<dt><a name="license"><kbd>LICENSE/S</kbd></a>
</dt><dd>
Display a short version of the <a href="../COPYING">GNU General
Public License</a> and exit.
</dd>
<dt><a name="-debug"><kbd>-DEBUG/S</kbd></a>
</dt><dd>
If you've compiled <kbd>hsc</kbd> in debug-mode, it will send lots of
information to <code>stderr</code>. Otherwise, this option is
equivalent to <kbd>STATUS=FULL</kbd>.
</dd>
<dt><a name="status"><kbd>STATUS/K</kbd></a>
</dt><dd>
Display several status messages (output goes to stderr). Legal
flags are:
<ul compact>
<li><kbd>QUIET</kbd>: no status messages
<li><kbd>LINE</kbd>: 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.
<li><kbd>VERSION</kbd>: display program title and version
<li><kbd>VERBOSE</kbd>: enable verbose status messages; this includes
the information displayed during the processing of <a href="features/exec.html"><code><$exec></code></a>
and some details about images, if <a href="options.html#getsize"><kbd>GetSize</kbd></a> has also been
enabled.
<li><kbd>FULL</kbd>: enable all status messages
</ul>
The above flags can be combined by separating them with a vertical bar (``<code>|</code>''),
eg <kbd>"STATUS=line|version"</kbd>, except for <kbd>QUIET</kbd>
and <kbd>FULL</kbd>
</dd>
</dl>
</body></html>
|