-*- mode: text -*-

Developers
==========

Xtla will be merged to GNU Emacs(we hope).
So the developers should be able to sign to FSF about
copyright assignment.

GNU Emacs, XEmacs and its version
=================================

We will support both Emacs and XEmacs. The developers are using:

Stefan Reichoer <stefan at xsteve . at>: GNU Emacs 21.3.1, GNU Emacs in CVS repository
Matthieu Moy <Matthieu.Moy at imag . fr>: GNU Emacs 21.2 (Solaris and Linux)
Masatake YAMATO <jet at gyve . org>: GNU Emacs in CVS repository
Milan Zamazal <pdm at zamazal . org>: GNU Emacs 21.3, GNU Emacs CVS
Martin Pool <mbp at sourcefrog . net>: ???
Robert Widhopf-Fenk <hack at robf . de>: XEmacs 21.4.5
Mark Triggs <mst at dishevelled . net>: GNU Emacs in CVS repository

gnuarch version
===============

gnuarch version which xtla's developers are using:

Stefan Reichoer <stefan at xsteve . at>:

Matthieu Moy <Matthieu.Moy at imag . fr>:
tla 1.2, tla 1.2.2rc2

Masatake YAMATO <jet at gyve . org>:
tla lord@emf.net--2004/dists--devo--1.0--patch-9(configs/emf.net-tla/devo.tla-1.2) from regexps.com

Milan Zamazal <pdm at zamazal . org>: tla, from Debian/testing.

Martin Pool <mbp at sourcefrog . net>:

Robert Widhopf-Fenk <hack at robf . de>:

Mark Triggs <mst at dishevelled . net>:


Key bind conventions
====================

See xtla-defs.el.

Symbol name conventions
=======================

- Face: Do not use a `-face' suffix for face names.

(About the reason, see
 http://mail.gnu.org/archive/html/emacs-devel/2004-03/msg00077.html)

- Functions and variables internal to xtla should be named tla--XXX
  Functions and variables used by the user should be named tla-XXX

Menu item conventions
=====================

See xtla-defs.el.

Mail conversions
================

Matthieu MOY <Matthieu.Moy at imag dot fr> wrote
in Message-ID: <1084790609.40a8975194dcd@webmail.imag.fr>

    I usually send a mail for a merge request only when the change
    involves a big portion of the file, to tell everybody to make sure
    they merge before doing any changes.

    However, when you send a mail, your suggestion of [MERGE REQUEST] flag
    is good.

Coding style
============

Robert Widhopf-Fenk <hack at robf dot de> wrote
in Message-ID: <16552.35294.211101.658893@gargle.gargle.HOWL>

    I really would like to see no lines longer than 80 chars in xtla.el.

Please, strip trailing whitespaces from your source files.

;; remove trailing whitespaces when saving.
(add-hook 'write-file-hooks 'delete-trailing-whitespace)

in your ~/.emacs.el can help.

Also, don't include any tabs in your source code. You should use

(setq indent-tabs-mode nil)

If you do not want to enable it in general, use something like the follwoing
in your ~/.emacs:

(defun rf-xtla-find-file-hook ()
  (when (and (buffer-file-name)
             (string-match "xtla" (buffer-file-name)))
    (message "Enabled XTLA settings for buffer %s" (buffer-name))
    (make-local-hook 'write-file-hooks)
    (add-hook 'write-file-hooks 'delete-trailing-whitespace nil t)
    (setq indent-tabs-mode nil)))

(add-hook 'find-file-hooks 'rf-xtla-find-file-hook)

Process management
==================

The function tla--run-arch now creates two buffer each time it is
called: a process buffer, and an error buffer. If the process is ran
synchronously, then the buffers are scheduled for deletion. If not,
the scheduling for deletion occurs in the process sentinel.

This means you will need to clone the buffer if you need to run arch
again while parsing the output buffers. (This was already necessary
with the old mechanism)

The variables tla--last-process-buffer and tla--last-error-buffer are
set each time a new process or error buffer is created. The value is
therefore meaningfull only until a new process is started. Avoid using
them when you're not sure the piece of code you're writting will not
one day be made asynchronous : This become meaningless in a process
sentinel.

I (Mark) have thrown in my two cents on the process management
stuff. I've added two functions: one for running tla synchronously
(tla--run-tla-sync), and one for running it asynchronously
(tla--run-tla-async). Their syntax is pretty much identical, which is as
follows:

  (tla--run-tla-(a)sync '("tla-arg1" "tla-arg2" .. "tla-argn")
                        :finished (lambda (output-buffer error-buffer status)
                                    ..)
                        :killed (lambda (output-buffer error-buffer status)
                                  ..)
                        :error (lambda (output-buffer error-buffer status)
                                 ..)
                        :output-buffer some-buffer
                        :error-buffer some-buffer
                        :related-buffer some-buffer)

The keywords :FINISHED, :KILLED and :ERROR supply callbacks, which are
functions that take four arguments:

  * the buffer containing the process output
  * the buffer containing the process error output; and
  * some indicator of the processes status (which can either be a
    return code or a string).
  * the argument list that the command was run with (e.g. ("undo"))

The :FINISHED callback is called in the case where the program finishes
successfully. The :KILLED callback is called when the program was
unexpectedly killed while running, and the :ERROR callback is called
when the program fails for some reason.

If :OUTPUT-BUFFER or :ERROR-BUFFER are supplied, the process will write
its standard/error output to these instead of generating buffers
automatically. Where these keywords are not given, new buffers will be
created, filled with program output and passed to the callback
functions.

Although it shouldn't ordinarily matter, it is worth noting that if
:OUTPUT-BUFFER or :ERROR-BUFFER are not given, the temporary buffers
that are created will be killed immediately after the callback
exits. This just means that if you plan on keeping those buffers around
for longer than just the scope of the callback, you'll need to clone
them first.

As a quick example, here is how you could asynchronously run a "tla
abrowse -s" and send the output to a printer (I'm not sure why you would
want to do this, but that's the great thing about contrived examples!):

  (defun print-archive (archive &optional postscript-output-file)
    "Run an abrowse on ARCHIVE and send the result to the printer."
    (tla--run-tla-async (list "abrowse" "-s" "-A" archive)
                        :finished `(lambda (output-buffer error-buffer
                                            status arguments)
                                     (with-current-buffer output-buffer
                                       (ps-print-buffer ,postscript-output-file)
                                       (message "Printed abrowse to %s."
                                                (or ,postscript-output-file
                                                    "printer"))))))

The only really noteworthy thing is the use of the backquoted
lambda. This is kind of like a poor man's lexical scoping, but it's a
useful way of capturing variables from the containing environment.

Name manipulator
================
See xtla-core.el.


Release & distribution process
==============================

* Development version
---------------------

The prefered way to get a development version is to use arch itself to
get the latest development version. However, xtla's configuration and
build system provides a way to distribute development tarballs:

make tarball

Will generate xtla-snapshot.tar.gz. This snapshot is put online every
nights on http://download.gna.org/xtla-el/xtla-snapshot.tar.gz

The documentation is made available separately on
http://download.gna.org/xtla-el/docs/xtla-snapshot.html

* Official releases
-------------------

Official releases will be made by the release manager, after
discussion on the mailing list.

The release manager will for example type the commands

  make RELEASE_ID=1.1 tarball

to generate xtla-1.1.tar.gz, that will be put online on
http://download.gna.org/xtla-el/xtla-1.1.tar.gz

This is the command I (Matthieu Moy) use to upload the tarball to
gna.org.

  scp -i ~/.ssh/gna_org xtla-1.1.tar.gz \
          moy@download.gna.org:/upload/xtla-el

The documentation is made available separately on
http://download.gna.org/xtla-el/docs/xtla-1.1.html

This is the command I use to generate and upload the documentation:

  make -C texinfo xtla.html
  scp -i ~/.ssh/gna_org texinfo/xtla.html \
         moy@download.gna.org:/upload/xtla-el/docs/xtla-snapshot.html


* Helper script
---------------

During the pre-1.0 phase, nightly snapshot tarballs and documentation
were made by Matthieu MOY. The scripts scripts/xtla-cron.sh was
actually doing the job, ran by cron every nights.

A future maintainer could reuse this script and adapt it to his
configuration.
