.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1991-1994, 1998, 2001 Peter Miller;
.\"	All rights reserved.
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 2 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program; if not, write to the Free Software
.\"	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
.\"
.\" MANIFEST: User Guide, The History Tool
.\"
.bp
.if t .2C
.nh 1 "The History Tool"
.LP
Aegis is decoupled from the history mechanism.
This allows you to use the history mechanism of your choice,
SCCS or RCS, for example.
You may even wish to write your own.
.LP
The intention of this is that you may use a history mechanism which
suits your special needs,
or the one that comes free with your flavour of 
.UX
operating system.
.LP
Aegis uses the history mechanism for file
.I history
and so does not require many of the features of SCCS or RCS.
This simplistic approach can sometimes make the interface to these
utilities look a little strange.
.nh 2 "Interfacing"
.LP
The history mechanism interface is found in the
project configuration file called
.I "config" ,
relative to the root of the baseline.
It is a source file and subject to the same controls
as any other source file.
The history fields of the file are described as follows
.nh 3 "history_create_command"
.LP
This field is used to create a new history.
The command is always executed as the project owner.
Substitutions available for the command string are:
.IP ${Input}
absolute path of source file
.IP ${History}
absolute path of history file
.LP
In addition, all substitutions described in \fIaesub\fP(5) are available.
.nh 3 "history_get_command"
.LP
This field is used to get a file from history.
The command may be executed by developers.
Substitutions available for the command string are:
.IP ${History}
absolute path of history file
.IP ${Edit}
edit number, as given by the history_\%get_\%command.
.IP ${Output}
absolute path of destination file
.LP
In addition, all substitutions described in \fIaesub\fP(5) are available.
.nh 3 "history_put_command"
.LP
This field is used to add a new change to the history.
The command is always executed as the project owner.
Substitutions available for the command string are:
.IP ${Input}
absolute path of source file
.IP ${History}
absolute path of history file
.LP
In addition, all substitutions described in \fIaesub\fP(5) are available.
.nh 3 "history_query_command"
.LP
This field is used to query the topmost edit of a history file.
Result to be printed on the standard output.
This command may be executed by developers.
Substitutions available for the command string are:
.IP ${History}
absolute path of history file
.LP
In addition, all substitutions described in \fIaesub\fP(5) are available.
.nh 3 "history_content_limitation"
This field describes the content style which the history tool is
capable of working with.
.IP ascii_text
The history tool can only cope with files which contain printable
ASCII characters, plus space, tab and newline.	The file must
end with a newline.  This is the default.
.IP international_text
The history tool can only cope with files which do not contain
the NUL character.  The file must end with a newline.
.IP binary_capable
The history tool can cope with files without any limitation on
the form of the contents.
.PP
When a file is added to the history (by either the
\fIhistory_\%create_\%command\fP or the \fIhistory_\%put_\%command\fP
field) it is examined for conformance to this limitation.  If there is
a problem, the file is encoded in either the MIME quoted printable or
the MIME Base 64 encoding (see RFC 1521), whichever is smaller, before
being given to the history tool.  The file in the baseline is unchanged.
.PP
On extract (the \fIhistory_get_command\fP field) the encoding is reversed,
using information attached to the change file information.  This is
because each put could use a different encoding (although in practice,
file contents rarely change that dramatically, and the same encoding is
likely to be deduced every time).
.nh 3 "history_tool_trashes_file"
Many history tools (e.g. RCS) can modify the contents of the file
when it is committed.  While there are usually options to turn this
off, they are seldom used.  The problem is: if the commit changes the
file, the source in the repository now no longer matches the object
file in the repository - \fIi.e.\fP the history tool has compromised the
referential integrity of the repository.
.LP
By default, when this happens Aegis issues a fatal error (at \fIintergate
pass\fP time).  You can turn this into a warning if you are convinced
this is irrelevant.  This would only make sense if the substition only
ever occurs in comments.  See \fIaepconf\fP(5) for more information
on the values for this field.
.nh 3 "Quoting Filenames"
.LP
The default setting is for Aegis to reject filenames which contain shell
special characters.  This ensures that filenames may be substituted
into the commands without worrying about whether this is safe.  If you
set the \fIshell_safe_filenames\fP field of the project \fIconfig\fP
file to \f(CWfalse\fP, you will need to surround filenames with the
\f[CW]${quote\fP \fIfilename\fP\f[CW]}\fP substitution.  This will only
quote filenames which actually need to be quoted, so users usually will
not notice.  This applies to all of the various filenames in
the commands in the sections which follow.
.so c3.1.so
.so c3.2.so
.so c3.3.so
.so c3.4.so