-*- text -*-

find-atfs is a package for GNU Emacs to provide access to AtFS
versions via the "find-file" function (the function usually invoked
with "C-x C-f").

For a terse introduction look at the beginning of the source file
find-atfs.el.

The dired-like interface "shapeTools mode" included in shapeTools 1.3
is not supported in this release.


Requirements

    find-atfs.el works with GNU Emacs version 19.22 or a later version
    of Emacs 19. find-atfs.el needs callp-err.el to work.

    The shapeTools version control commands retrv, save, vbind, vcat,
    vl, and vlog must be available in your command search path $PATH.
    Otherwise you have to change the variables atfs-*-command in
    find-atfs.el (near the beginning of the file).


Install

    To use find-atfs, load the file find-atfs.el (or find-atfs.elc, if
    you have byte-compiled it). If you want to load find-atfs on Emacs
    startup, copy find-atfs.el or find-atfs.elc and callp-err.el or
    callp-err.elc into a directory in your Emacs load path and put the
    following line into your Emacs startup file $HOME/.emacs:

	(load "callp-err")
        (load "find-atfs")


Visiting versions

    When find-atfs.el is loaded, AtFS versions can be visited in an
    Emacs buffer like Unix files by giving the version ID as argument
    to find-file. E.g. to visit version 2.6 of mumble.c in an Emacs
    buffer, type

	C-x C-f mumble.c[2.6] RET

    Instead of the version number 2.6 you can also use a symbolic name
    or a version selection rule (see vbind(1)) to select the desired
    version.

    If no busy version of mumble.c exists, you can type

	C-x C-f mumble.c RET

    and find-file will read the most recent version of mumble.c into a
    buffer. This buffer is write-protected and you will see the minor
    mode "AtFS" in the mode line.


Checking out an AtFS version

    If you want to edit a version in an Emacs buffer, use the command
    toggle-read-only (C-x C-q). If you answer with "yes" to the
    question "Check this version out with lock?", Emacs will ask you
    for a change intent in a separate buffer. After typing the change
    intent, continue with C-c C-c. The version is then checked out
    with lock. The busy version is read into a buffer which you can
    edit as usual.

    If the version is already locked by someone else, you will get an
    appropriate error message.

    The buffer containing the AtFS version is killed when you check
    the version out as a file. If you want to keep the buffer, set the
    option atfs-kill-version-buffer-on-checkout to nil. (See below for
    setting of options.) The buffer of a version is then put to the
    end of the buffer list on checkout.

    Find-atfs tries to keep the point at the appropriate location of
    the file on checkout and on checkin i.e. at the same context.
    (This may not always succeed.)  If you don't like that, set the
    option atfs-keep-position-on-checkout to nil.


Checking in a file as AtFS version

    To check a busy file in as AtFS version, type C-x C-q in the file
    buffer. If you answer the question "Check this file in as AtFS
    version?" with yes, Emacs will ask you for a log message. After
    typing the log message, continue with C-c C-c. The file is then
    checked in as AtFS version. If no AtFS archive exists, save(1)
    will create it.


File name completion

    To make Emacs do file name completion on version names, type C-u
    before invoking find-file. Be aware that file name completion on
    versions is slow.

    If you want to enable file name completion on version names
    permanently, set the option atfs-find-file-always-complete to t
    in your emacs startup file by

	(setq atfs-find-file-always-complete t)


File name completion on histories

    By default, atfs file name completion shows all known names in a
    directory without any version specifications. Behind the name
    you may type the desired version number or alias name in square
    brackets or omit the version specification to visit the most
    recent version. If you want all versions to be listed in your
    *completion* buffer, set the option atfs-completion-show-versions
    to t. histories are shown in the *completion* buffer. You then
    have to type the desired version number yourself or omit the
    version number if you want to visit the most recent version.


Setting options

    To enable an option, set its value to t. You can do that
    interactively by typing

        M-x set-variable RET <option-name> RET t RET

    or by putting a setq statement into your $HOME/.emacs file like
    this: 

        (setq <option-name> t)

    (In either case, replace <option-name> by the literal name of the
    option.)

    To disable an option, set its value to nil.


Option summary

    atfs-kill-version-buffer-on-checkout	Default value: t
    
        If non-nil, kill the buffer of a version when it is checked
        out. Otherwise put it at the end of the buffer list.

    atfs-find-file-always-complete		Default value: nil

        If non-nil, always do completion on version IDs in find-file.
        Otherwise completion is done only with prefix argument.

    atfs-completion-show-versions	        Default value: nil

        If non-nil, all versions are shown when doing completion.

    atfs-keep-position-on-checkout		Default value: t

        If non-nil, try to keep point at the same position on check
        in/out. This will not always succeed.

    There are some other option variables mentioned in find-atfs.el,
    but these are non-operational yet.


Problems

    - find-atfs depends strongly on some internals of Emacs, so this
      version may not work with future versions of Emacs

    - completion on full version IDs is quite slow

    - environment variables in pathnames are not expanded during file
      name completions


Redefined functions

    find-atfs redefines some Emacs functions to make Emacs aware of
    AtFS versions. These are:

      - file-writable-p
      - file-exists-p
      - toggle-read-only
      - find-file

;;; EOF
