SysLog Setup
============

SysLogStp is used to configure behaviour of the SysLog (system
logging) module within RISC OS. You should not need to run it
separately; it integrates into !Configure. However, if run as a
normal application it will install an icon on the icon bar in
the usual way.

Interactive help is available (load !Help from Apps).


Notes
-----

SysLog Setup reads its information in the following order:

1. from the entries in the SysLog configuration file (the
   file that it re-saves when the Save button is clicked);
2. from the log files it finds on disc;
3. from active logs in memory.

Default settings are set up initially in case no other logs are
known to the system. As logs are read in during steps 1 to 3,
if duplicate log entries are found, then settings specified in
each subsequent duplicate entry will override those already in
force for that log. Thus it would theoretically be possible to
specify several different options for a particular log over a
number of configuration lines (as long as each line began with
the correct log name). However, this is not recommended, so if
SysLog Setup encounters multiple entries for a single log in
the configuration file, or multiple default settings, it will
issue a warning to that effect.

When writing the settings file, in order to avoid ambiguity,
all available SysLog options are written for each entry and
duplicate entries will be eliminated.


Changed entries
---------------

When editing a log, an asterisk is marked against its name
(both in the display field and in the menu of logs) to show
whether it has been edited or not. This asterisk should be
interpreted as meaning "the log has been EDITED" rather than
definitively that "the log has been CHANGED"; for example, if
the Set button is used, or a new log chosen from the menu when
the current log is edited but not saved, the asterisk marker
will be turned on permanently for the current log because
SysLog Setup cannot be certain whether or not the settings have
changed from their original states.

The Set button may be clicked with Select at any time to
enforce the current settings for the log currently being
edited; nothing will be saved to disc if Set is clicked.
If the click is with Adjust, then SysLog will step through
every known log and register its current details with SysLog.

The Save button always saves the configuration file to disc,
and always enforces all settings in all logs (the latter
operation is equivalent to clicking Adjust on Set).


Re-scanning logs
----------------

When changes are made and the settings saved, SysLog Setup
causes the SysLog module to honour all new settings. However,
the Set button can be used to enforce the current settings for
a single log, or all logs, without saving the settings to disc.
This means that the SysLog settings currently in force may not
match the settings saved in the SysLog configuration file.

When SysLog Setup starts up, it reads all log settings from
disc and then overrides them with the current settings in
memory. This is normally the most helpful behaviour, but on
rare occasions it may be desirable to be certain that the
settings being edited are those saved on disc, rather than
those stored in memory.

Therefore, a 'Re-scan logs' menu option is provided on the
main window menu. This features two options:

1. Re-scan all logs, including overrides from memory

(Choosing the parent 'Re-scan logs' menu item performs the
same action as choosing this first option on the sub-menu.)

This causes all log information to be rescanned, complete with
overrides taken from the current settings in memory, exactly as
when SysLog Setup was first launched. This is useful if you
want to be certain that you are seeing all the options as they
currrently exist on your system.

2. Re-scan only the saved logs, without memory overrides

This causes log information to be read from disc only; the
SysLog module is not interrogated for current information, so
the settings shown in SysLog Setup will be exactly the same as
those currently saved on disc. Note that any static logs known
to the SysLog module (those stored entirely in memory) will be
excluded unless information has already been saved about them
in the configuration file on disc.

In either case, you will be prompted to confirm the menu
action, as re-scanning the logs will cause the loss of any
unsaved changes made within SysLog Setup.
