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
|
<!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.gif" ALT="Contents" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<IMG SRC="image/noindex.gif" ALT="-----" ALIGN="middle" WIDTH="70" HEIGHT="16">
<A HREF="copy.html"><IMG SRC="image/copy.gif" ALT="Copyright" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="index.html"><IMG SRC="image/back.gif" ALT="Up" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="install.html"><IMG SRC="image/prev.gif" ALT="Previous" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="examples.html"><IMG SRC="image/next.gif" 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 section covers which
<A HREF="#options">options</A> and
<A HREF="#switches">switches</A> you can pass to <KBD>hsc</KBD>,
and which <A HREF="#exitcodes">exit codes</A> are returned to CLI.
<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 is considered a decimal number.
If an invalid number is specified, an error will be returned.
<DT><KBD>/A</KBD> - Required.
<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="options">Options</A></H2>
<DL>
<DT><A NAME="from"><KBD>FROM/M</KBD></A>
<DD>
Specifies the input filename. To use <CODE>stdin</CODE> as
input file, the pseudo filename <CODE>STDIN</CODE> (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 <A HREF="features/spctags.html#include"><CODE><$include></CODE></A> in the hsc-source.
<DT><A NAME="to"><KBD>TO/K</KBD></A>
<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>
<DT><A NAME="extension"><KBD>EXTENSION/K</KBD></A>
<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.
<DT><A NAME="msgfile"><KBD>MSGFILE/K</KBD></A>
<DD>
Redirects messages to a file. By default, <CODE>stderr</CODE> ist used.
<DT><A NAME="msgformat"><KBD>MSGFORMAT/K</KBD></A>
<DD>
Describes how messages should be displayed. Conversion specifications:
<PRE>
%f filename
%x, %y location in file (column, line)
%c message class
%i message id (numeric)
%m message text
%n inserts a linefeed
</PRE>
Example: To get GCC-like messages, use
<CODE>MSGFORMAT="%f:%y: %c %i: %m"</CODE>.
<DT><A NAME="prefsfile"><KBD>PREFSFILE/K</KBD></A>
<DD>
Specifies filename for <A HREF="features/prefs.html">sytax-definition</A>
to be used, if you don't want to use the defaults.
<DT><A NAME="prjfile"><KBD>PRJFILE/K</KBD></A>
<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.
<DT><A NAME="define"><KBD>DEFINE=DEF/K/M</KBD></A>
<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: <CODE>DEFINE "hugo:string=hugo was here"</CODE>
<DT><A NAME="ignore"><KBD>IGNORE=IGN/K/M</KBD></A>
<DD>
Ignore warning message number. Usually, <KBD>IGNORE</KBD> needs a numeric
argument and can occur multiple. Example:<BR>
<BLOCKQUOTE>
<KBD>IGNORE=21 IGN=18 IGN 3</KBD> (ignore warnings #21, #18, #3)
</BLOCKQUOTE>
Additionally, you can specify some special values, which will ignore
whole groupss of messages:
<UL>
<LI><KBD>ALL</KBD>
Ignore all non-error messages
<LI><KBD>NOTES</KBD>
Ignore all notes
<LI><KBD>BADSTYLE</KBD>
Ignore all bad style warnings
</UL>
These values add new messages to the list of messages
to be ignored, but do not reset any <KBD>IGNORE</KBD>s passed before.
<DT><A NAME="mode"><KBD>MODE/K</KBD></A>
<DD>
Set base mode for syntax check. Legal values are <KBD>PEDANTIC,
NORMAL</KBD> and <KBD>RELAXED</KBD>. Default is <KBD>NORMAL</KBD>.
This only disables several messages and warnings from the beginning.
Any <KBD>IGNORE</KBD>s passed before are reseted.
<DT><A NAME="quotestyle"><KBD>QUOTESTYLE/K</KBD></A>
<DD>
Specifies which kind of quotes should be used to surround
attribute-values. <KBD>KEEP</KBD> keeps the user-kind,
<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.
<DT><A NAME="includedir"><KBD>INCLUDEDIR=IDIR/K/M</KBD></A>
<DD>
By default, only the current directory is scanned for files
to be included (using the CLI 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.
<DT><A NAME="status"><KBD>STATUS/K</KBD></A>
<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
Included files 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>
<DT><A NAME="striptags"><KBD>STRIPTAGS/K</KBD></A>
<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>.
<DT><A NAME="iconbase"><KBD>ICONBASE/K</KBD></A>
<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.gif" 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>.
<DT><A NAME="serverdir"><KBD>SERVERDIR/K</KBD></A>
<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:
<CODE>SERVERDIR=aws:home</CODE> might work fine under AmigaOS,
<CODE>SERVERDIR=/user/sepp/public_html</CODE> could be used
on an Unixoid system.
</DL>
<H2><A NAME="switches">Switches</A></H2>
<DL>
<DT><A NAME="help"><KBD>HELP/S</KBD></A>
<DD>
Display a short help message and exit.
<DT><A NAME="license"><KBD>LICENSE/S</KBD></A>
<DD>
Display a short version of the <A HREF="../COPYING">GNU General
Public License</A> and exit.
<DT><A NAME="compact"><KBD>COMPACT/S</KBD></A>
<DD>
<A HREF="features/strip.html">Strip redundant linefeeds
and white-spaces</A> from output.
<DT><A NAME="-debug"><KBD>-DEBUG/S</KBD></A>
<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>.
<DT><A NAME="getsize"><KBD>GETSIZE/S</KBD></A>
<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;
<DT><A NAME="msgansi"><KBD>MSGANSI/S</KBD></A>
<DD>
Uses ANSI-sequences to make messages more readable. This option is
recommended to be used by people who are not smart enough to integrate
<KBD>hsc</KBD> in some of the existing project-management environments.
<DT><A NAME="rplcent"><KBD>RPLCENT/S</KBD></A>
<DD>
<A HREF="features/rplcent.html">Replace special characters</A> with
their entities (eg ``<CODE>ü</CODE>'' becomes
``<CODE>&uuml</CODE>'').
<DT><A NAME="rplcquote"><KBD>RPLCQUOTE/S</KBD></A>
<DD>
Replace double-quotes (``<CODE>"</CODE>'') found in the text by
``<CODE>&quot;</CODE>''. This does not affect quotes used inside
attribute-values.
<DT><A NAME="smartent"><KBD>SMARTENT/S</KBD></A>
<DD>
Replace special characters ``<CODE>&</CODE>'',
``<CODE><</CODE>''
and ``<CODE>></CODE>'' with their entities
(<CODE>&amp;, &lt;</CODE> and <CODE>&gt;</CODE>) if they are
surrounded by white-spaces.
<DT><A NAME="stripbadws"><KBD>STRIPBASWS/S</KBD></A>
<DD>
Strip bad white spaces that would have caused <A HREF="messages.html#message.78">message #78</A>
or <A HREF="messages.html#message.79">message #79</A>; this will not strip those which cause
<A HREF="messages.html#message.47">message #47</A>. The main advantage of this switch is that
it allows you to write well structured macros.
<DT><A NAME="stripcomment"><KBD>STRIPCOMMENT/S</KBD></A>
<DD>
Strip all SGML-comments from input.
<DT><A NAME="stripexternal"><KBD>STRIPEXTERNAL/S</KBD></A>
<DD>
Strip tags which refer to an external URI.
</DL>
<H2><A NAME="exitcodes">Exit Code</A></H2>
<P>The exit-code <KBD>hsc</KBD> returns to the CLI 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.
</BODY></HTML>
|
