tutorials/ctinfo-messaging.md

+
+If the programmer did something wrong, and you want to tell them about it, you need to add an error message.
+
+You can get functions for this using `#include "ctinfo.h"`
+
+# Formatting
+
+You should mainly use the `CTIerror` function to print error messages or `CTIwarn` to make warnings.
+You can create multi line error messages using `CTIerrorBegin`, `CTIerrorContinued` and `CTIerrorEnd`.
+
+**Inside error messages do not use `\n` characters!** Instead, use `@`.
+This is done to allow for better formatting of error messages using compiler flags.
+These `@` be replaced by new lines if needed based on compiler flags.
+
+## Flags
+
+There are a few flags that can be used to control the output of error messages.
+
+- `-cti-message-length <n>` 
+Insert extra line breaks for messages with lines that are
+longer than <n> characters. The value 0 implies no extra
+line breaks. (default: terminal width if stderr outputs to a console, 0 otherwise = 207)
+
+- `-cti-no-color`   Disables all color output. Color is not yet supported.
+
+- `-cti-single-line` Omits all line breaks within messages and sets -cti-message-length 0.
+
+- `-cti-primary-header-format <string>` Customize the header of the first line of all message types.
+The string must contain exactly one `%s` which will be replaced by a possible location (GNU format), 
+followed by the message type (error, warning or note).
+The string may also contain `@` to indicate desired line breaks. (default: "%s:@")
+
+- `-cti-continuation-header-format <string>` Customize the header of the remaining lines in multi-line
+messages (Created with CTIerrorBegin).
+The string must contain exactly one `%s` which will be replaced by a possible location (GNU format), 
+followed by the message type (error, warning or note).
+The `@` character is not converted into line breaks in the continuation header. 
+Note that `%.s` or `%.0s` allows the location and message type to be omitted.
+This is what is done by default with the default value: `%.0s   `.
+
+# Verbosity levels
+
+There are 4 verbosity levels.
+The verbosity level is controlled by the command line option -v and the global variable `verbose_level`.
+
+Default values are 1 for the product version and 3 for the developer version.
+
+## Verbose level 0:
+
+Only error messages are printed from the following functions:
+
+- `CTIerror` - Create an error message with a location
+- `CTIerrorBegin` - Beging an error message where you do not have the entire message yet
+- `CTIerrorContinued` - Append to an error message that you started with CTIerrorBegin.
+- `CTIerrorEnd` - End an error message started with CTIerrorBegin
+- `CTIerrorRaw` - Prints a preformatted error message and counts increments the error counter. Should only be used in conjunction with CTIgetErrorMessageVA, but should
+ideally be completely avoided in favor of `CTIerror()`
+- `CTIerrorInternal` - Produces an error message without file name and line number, but specifies the phase where the compiler failed. 
+This function does not respect all cti command-line arguments to avoid potential crashes or hangs during error handling.
+- `CTIgetErrorMessageVA` - This function allows for split-phase error messages:
+```
+str_buf = CTIgetErrorMessageVA (line, fname, format, ...args);
+CTIerrorRaw (SBUFgetBuffer (str_buf));
+SBUFfree (str_buf);
+```
+equates to
+```
+CTIerror (LINE_TO_LOC (line), format, ...args);
+```
+
+This allows preparing error messages in advance and activating
+them when needed.
+
+Afterwards, an abort can be triggered with `CTIabortOnError()`;
+
+
+## Verbose level 1:
+
+Error messages and warnings are printed.
+
+- `CTIwarn`
+
+## Verbose level 2:
+
+Error messages, warnings and basic compile time information, e.g. compiler
+ phases,  are printed.
+
+- `CTIstate`
+
+## Verbose level 3:
+
+Error messages, warnings and full compile time information are printed.
+CTInote (const struct location loc, const char *format, ...) PRINTF_FORMAT (2, 3);
+
+## Verbose level 4+:
+
+Additional compile time information is provided that typically is only
+of interest in certain situation.
+
+- `CTItell`
+
+## Additional 
+
+These additional functions also exist in `ctinfo.h`.
+
+- `CTIabort` - Stop the compiler right now with a message.
+- `CTIabortOnBottom` - Prints a preprocessed error message obtained from CTIgetErrorMessageVA and aborts the compilation.
+- `CTIabortOutOfMemory` - Produces a specific "out of memory" error message without allocating more memory
+- `CTIabortOnError` - Terminates compilation process if errors have occurred. 
+
+
+