# Messages

`Hsc` is able to produce lots of different warnings and errors when parsing hsc-sources. The are divided into several classes, and there is a possibility to filter out specific messages or whole message classes. There are also possibilities to change the appearance of messages and redirect them to a file, making it easy to integrate `hsc` into existing developer environments.

## Message Elements

For example, a typical message could be:

    hugo.hsc (17,23): Warning 11: unknown tag <sepp>

with being..

- ..`hugo.hsc` the name of the input file that caused the message.
- ..`17` and `23` the position in input file. 17 denotes the line, and 23 the column of the item that caused the message
- ..`Warning` the message class. There are several other messages classes: Note, Bad-style, Portability-problem, Error or Fatal error. See below for details about those message classes.
- ..`11` the number of the message. You can use this to quickly find the description in the list of message or to suppress it in further runs using `Ignore`.
- ..`unknown tag <SEPP>` the message text, which describes what went wrong.

The message about would suggest to load the file hugo.hsc in your editor and go to line 17, column 23.

## Message Classes

Note is a message only for the user's information. It can be suppressed using `Ignore`.

Bad-style informs the user that his although legal HTML code includes constructs that indicate a bad style. It can be suppressed using `Ignore`.

Portability-problem informs the user that his although legal HTML code includes constructs can lead to problems on old or buggy browsers. It can be suppressed using `Ignore`.

Warning tells you that your source includes some problematic parts that can lead to problems with several browsers. It can be suppressed using `Ignore`.

Error indicates that there is something wrong with your HTML source. Conversion will continue, but no output will written be written after finishing it.

Fatal error tells you that something serious is wrong and there is no way for `hsc` to recover and continue the conversion. No output will be written.

There is also a class called internal error messages, which is used by `hsc` to report that `hsc` itself is broken. Normally this should not happen, but if it does, you have found a bug. To find out more about what to do in such a case, see the chapter on ``Known Bugs, Problems And Limitations''.

## Message Options

There are several commandline options to modify the behavior of `hsc`'s messages. You can suppress messages you are not interested in and you can redirect them to a file and change the output format, e.g. to pipe them to an external message browser. On some systems, you can even send them to some selected message browsers without messy piping and scripting.

### Ignore/Enable Certain Messages and Classes

If you think that `hsc` reports too much or too little about problems in your source code, you can specify several options to change its behavior.

The first one—and also the one with the biggest impact—is `MSGMODE`. This switches `hsc` into one of three basic modes for the syntax check:

- `PEDANTIC` - Whine about nearly everything, including the whole bunch of ``bad style'' and portability problems. Also minor changes to the output like the replacing of entities is reported in this mode.
- `NORMAL` - This is the default that should give a reasonable cocktail of messages, reporting most problems that average users should understand.
- `RELAXED` - Perform only a very basic check and ignore nearly everything that might cause problems. This should only be used if you do not care much about your HTML code (Read: you are a jerk).

These modes, however, give only very rough control over the amount of messages. For the fine-tuning, the more sophisticated `IGNORE` and `ENABLE` exist.

Unless `MSGMODE=NORMAL` is OK for you, you have to specify `MSGMODE` in the command line before `IGNORE` or `ENABLE` is used the first time as it resets several of the internal data structures.

`IGNORE` can be used to suppress single messages or whole message classes, if you are not interested in them. This option can show up in the command line call multiple times, for example:

`IGNORE=18 IGN=21 IGN 22` - ignore warnings #18, #21, #22

You can also specify a whole list of messages, separated by a vertical bar (```|`''), for instance:

`IGNORE=18|21|22` - same as the above example

(If the vertical bar is used as piping character, you have to quote this value: `IGNORE "18|21|22"`)

There are some special, non-numeric values you can use to ignore whole groups or classes of messages:

- `ALL` - Ignore all non-error messages
- `JERK` - Ignore all stuff perpetrated by jerks only
- `NOTE` - Ignore all notes
- `PORTABILITY` - Ignore all portability problems
- `STYLE` - Ignore all bad style warnings

If you don't care about portability problems and some other messages, but still want to have a quite exhaustive check, you could use something like this:

`MSGMODE=pedantic IGNORE=portability|46|51`

If on the other hand you are quite satisfied with the `NORMAL` check but want to see one particular message (e.g. replaced icon entities), this should do the trick:

`MSGMODE=normal ENABLE=77`

You can combine these options to even more complex rules:

`MSGMODE=pedantic IGNORE=note ENABLE=77`

This first enables all messages, then disables all notes but finally enables again one specific note for message #77.

To find out the number of a certain message to enable, look at the list of messages. To ignore a message, simple get the number from the console once an unwanted message shows up the first time.

### Redirecting Messages and Changing the Message Format

`MSGFORMAT` specifies the appearance of messages, for example concerning the sequence of the elements described before. The message format can contain several placeholders that are replaced by the message elements described above:

%f | filename
%x, %y | location in file (column, line)
%c | message class
%i | message id (numeric)
%m | message text
%n | inserts a linefeed
%% | inserts percent sign (```%`'')

To for example get GCC-like messages, use `MSGFORMAT="%f:%y: %c %i: %m"`.

To disable output to the console, specify an empty string: `MSGFORMAT=`. This is probably useful only if you use a message browser (see below).

`MSGFILE` can be used to redirect messages to a file, from where they can be processed for example by some message parser that controls your editor.

For an example script that invokes hsc, redirects its messages and sends them to a message browser, see grafflwerk/hScMsg.rexx.

### Using a Message Browser

By default, `hsc` writes messages to the console where it was started from. For the user this means to read the filename and position, switch to his editor and go to the line told. Because this is pretty troublesome, many people use message browser where all messages are listed nicely sorted by file. Clicking on a message puts the editor to front and makes it jump to the requested position.

With the commandline option `MSGBROWSER` you can specify one of the following browsers (case insensitive):

- `ScMsg`: The message browser coming with the SAS/c compiler for AmigaOS. As ARexx is used to communicate with the browser, `RexxMast` has to be running. The browser is expected to be in `sc:c/scmsg` and will be started automatically if it is not already running.
- `VBrowse`: This uses public domain `VBrowse` message browser for AmigaOS coming with the freely distributable `VBCC` compiler. On the hsc support page there is an archive containing this browser and describing how to use it together with `hsc`. But you better keep your expectations low - keep in mind that it is public domain and the compiler is the main application of this package.
- `ThrowBack`: This uses the throwback mechanism popular under RiscOS.
- `ANSI`: This is no browser but only uses some ANSI codes when sending the message to the console. Your console has to support ANSI escape sequences (most do nowadays). This is only useful if you can not find any more comfortable way to read the messages.

So to to use `ScMsg`, specify `MSGBROWSER=SCMSG`, for throwback set `MSGBROWSER=Throwback`.

If you specify a message browser on a system that does not support it, e.g. attempting to `Throwback` under NeXTStep, no browser will be used. That means you do not have to change your Makefile if you want to work on another system for a short time.

Note that status messages and non-input related error messages are still viewed in the console.

### Limiting Messages

By default, `hsc` stops to parse once more than 40 messages or 20 errors have show up. In such a case, you should either start to `Ignore` messages or fix errors.

If you don't like these numbers, you can change them using `MAXMSG` respectively `MAXERR`. The value `0` represents an "infinite" amount of messages.

Note that nested messages with all those ```location of previous call`'' texts still count as one, independent of the nesting level.