HELP VED_AUTOSAVE                                Aaron Sloman June 1991

ENTER autosave <number>
ENTER autosave off
ENTER autosave
ENTER autosave reset

LIB VED_AUTOSAVE

This library extends the * VEDAUTOWRITE facility, by enabling VED to
write all altered files at regular specified intervals, keeping an extra
backup file for each one per session if necessary.

This considerably enhances the security of VED in contexts where there
is a risk of a crash, or a disastrous editing error.


         CONTENTS - (Use <ENTER> g to access required sections)

 -- Introduction
 -- Running ved_autosave
 -- ENTER autosave <number>
 -- ENTER autosave off
 -- ENTER autosave
 -- ENTER autosave reset
 -- Setting up your vedinit.p, and altering defaults
 -- vedautosave_minutes: time interval between activations
 -- vedautosave_min_write: minimum change required for saving
 -- vedautosave_preserve: The "per session" backup mechanism
 -- vedautosave_min_preserve: minimum number of lines for extra backup
 -- vedset_autosave: Running the timer under program control
 -- vedautosave_write: the procedure that saves the files
 -- Relationship with vedautowrite
 -- Putting the library into a saved image
 -- See also

-- Introduction -------------------------------------------------------

This library is intended as an improvement to the * VEDAUTOWRITE
mechanism which saves a file ONLY when the number of changes on that
particular file exceeds the value of the variable vedautowrite, which
means that if the system crashes after you have made a large number of
small changes on different files without writing them you can lose a lot
of work.

This library provides a mechanism for automatically saving files that
have been changed. It uses a timing mechanism instead of simply counting
changes in each file, and can save all current VED files to disk at
regular time intervals, coping with the situation where you have made
several changes to lots of files, none of them exceeding vedautowrite.
This library uses * SYS_TIMER, a new facility in Poplog since Version
14.02. (See also REF * TIMES)

Note: files for which -vedwriteable- is false are NOT saved.

Users can control the behaviour of -ved_autosave- in various ways, e.g.

  - Specifying the interval at which saving is invoked
    (see vedautosave_minutes)

  - Specifying whether an extra backup file should be kept for each file
    changed during a Poplog session, and if so, how it should be done
    (see vedautosave_preserve)

  - Specifying whether all changed and writeable files are saved each
    time or only those with a minimum numberof changes
    (see vedautosave_min_write)

  - Redfining the procedure invoked at intervals by the timer to save
    files.
    (see vedautosave_write)

These options and additional facilities are described in more detail
below.


-- Running ved_autosave ----------------------------------------------

The library can be invoked interactively by using one of the commands:

-- ENTER autosave <number>

    Assigns <number> to vedautosave_minutes, to set the timer interval,
    and displays the current setting and tells you how much time is
    left. <number> can be integer or decimal, representing the number of
    minutes between saves. E.g. to make it save every 7 and a half
    minutes do

    ENTER autosave 7.5


-- ENTER autosave off

    This turns off automatic saving of files. Turn it on again by giving
    the command with a number of minutes, or with no argument.

-- ENTER autosave

    Shows the current setting and tells you how much time is left, or
    tells you if the automatic saving has been turned off.


-- ENTER autosave reset

    This clears the property that remembers which files have had their
    "per session" backup. This means that if any of them are altered
    again they will receive an extra "per session" backup.


-- Setting up your vedinit.p, and altering defaults -------------------

If you want the mechanism to operate whenever you run VED, then put the
following into your vedinit.p to load the program:

    uses ved_autosave;

The variables defined below can then be set as required, e.g. assigning
a number to vedautosave_min_write can be used to suppress autosaving of
files with very few changes.


-- vedautosave_minutes: time interval between activations ------------

vedautosave_minutes -> <number>                       [active variable]
<number> -> vedautosave_minutes

This active variable has a value that defaults to 5 minutes. Updating it
changes the timer interval. If you want to make it 2.5 minutes do:

    2.5 -> vedautosave_minutes;

in your vedinit.p

However, you can do this only AFTER you have loaded the library, not
before. E.g.

    uses ved_autosave
    2.5 -> vedautosave_minutes;


-- vedautosave_min_write: minimum change required for saving ---------

This is an integer, specifying the minimum value of -vedchanged- in each
file below which the file should not be written.

So if you don't want changed files written unless they have more than 50
changes then do

    50 -> vedautosave_min_write;

The default is 0 meaning that files with any changes at all will be
written.

NOTE: changes are counted by the global variable * vedchanged. Some
procedures, like ved_gs make many changes but increment vedchanged
only by 1.


-- vedautosave_preserve: The "per session" backup mechanism -----------

vedautosave_preserve -> <item>                                [variable]
<item> -> vedautosave_preserve

This variable, whose value should be a boolean, a string, an integer or
a procedure, controls whether the automatic saving mechanism creates an
initial EXTRA backup file for each file edited during the current
session, provided that the file has more than vedautosave_min_preserve
lines in the buffer. (See below)

The decision concerning EXTRA backup is taken as follows:

-   If -vedautosave_preserve- is false, then no special action is taken.

    Otherwise an extra backup file is created for each file containing
    more than vedautosave_min_preserve lines, when it is first saved, in
    the following way:

-   If vedautosave_preserve is a string that names a directory then the
    first time any file is saved in a particular Poplog session the
    current version on disk is copied to that directory. If necessary
    the usual Poplog backup version will be created for the copied file.
    (I.e. the extra backups are themselves backed up.)

-   If it is a string but not a directory (e.g. '.bak', or '~~') then
    the first time any file is saved in a particular Poplog session the
    current version on disk is copied to a file with the same pathname,
    but with that string appended. If that suffix was used in a previous
    session then the usual Poplog backup version will be created for
    that file (with "-" appended on UNIX).

-   If it is an integer, then that is temporarily assigned to
    -vedversions- so that up to that  number of backup versions will be
    created (depending on how many existed previously).

-   If it is a (user-defined) procedure, then the procedure is applied
    to the file's path name. E.g. the procedure could make a copy in a
    backup directory that differs for different files.

-   If it is anything else (e.g. -true-, the DEFAULT) then on the first
    save a backup copy will be made with an additional version suffix,
    (e.g. '--', or '---' on UNIX or '__' or '___' on VMS) corresponding
    to 1 plus the value of -vedversions- if set, otherwise the value of
    -pop_file_versions-.

Thus, the first time a file is autosaved in a particular Poplog session,
an extra copy will be made that is not altered by the normal backup
mechanism when VED saves the buffer contents. However, the command

    ENTER autosave reset

will re-start "per session" backups for the current session.


-- vedautosave_min_preserve: minimum number of lines for extra backup

The role of this variable is described in connection with the use of
vedautosave_preserve.


-- vedset_autosave: Running the timer under program control ---------

vedset_autosave(<boolean>)                                  [procedure]

This procedure takes a boolean argument. If the argument is -true-, it
starts the timer, using the current value of vedautosave_minutes. If the
argument is -false- it turns automatic saving off. It can be turned
on again either using this procedure or using
    ENTER save <number>


-- vedautosave_write: the procedure that saves the files --------------

vedautosave_write()                                          [procedure]

The user-definable procedure -vedautosave_write- is invoked at regular
intervals defined by the value of -vedautosave_minutes-. This is the
procedure that takes account of the variables -vedautosave_preserve-
and -vedautosave_min_write-.

Users considering altering it should look at the default definition of
-vedautosave_write- in LIB * VED_AUTOSAVE


-- Relationship with vedautowrite -------------------------------------

If you wish to disable the ordinary vedautowrite mechanism described in
HELP * VEDAUTOWRITE, which is triggered by number of changes in the
current file do

    false -> vedautowrite;

Alternatively assign a largeish number as a precaution, e.g. 2000.


-- Putting the library into a saved image -----------------------------

When it is compiled LIB * VED_AUTOSAVE concatenates the procedure

    vedset_autosave(%true%)

with -pop_after_restore- so that the timer is properly initialised when
saved images are started up.


-- See also -----------------------------------------------------------

HELP * VEDAUTOWRITE
HELP * VEDVERSIONS
HELP * POP_FILE_VERSIONS
REF  * TIMES/sys_timer


--- C.all/help/ved_autosave
--- Copyright University of Sussex 1991. All rights reserved. ----------
