264 lines
9.4 KiB
Plaintext
264 lines
9.4 KiB
Plaintext
-*- mode: text -*-
|
|
|
|
Developers
|
|
==========
|
|
|
|
DVC will be merged to GNU Emacs(we hope).
|
|
So the developers should be able to sign to FSF about
|
|
copyright assignment. In other words, we can accept
|
|
only patches whose author agrees to sign to FSF.
|
|
CONTRIBUTORS file is for tracking the contributors
|
|
and their copyright assignments.
|
|
|
|
CONTRIBUTORS file is maintained by Michael Olson.
|
|
|
|
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 following
|
|
in your ~/.emacs:
|
|
|
|
(defun rf-dvc-find-file-hook ()
|
|
(when (and (buffer-file-name)
|
|
(string-match "xtla\\|dvc" (buffer-file-name)))
|
|
(message "Enabled Xtla/DVC 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-dvc-find-file-hook)
|
|
|
|
Non-trivial macros should include the form:
|
|
(declare (indent INDENT-SPEC) (debug DEBUG-SPEC))
|
|
The INDENT-SPEC tells Emacs' indentation commands how to indent the form,
|
|
whereas DEBUG-SPEC tells Edebug how to instrument the form for debugging.
|
|
See: (info "(elisp) Indenting Macros") and
|
|
(info "(elisp) Edebug and Macros") for more info.
|
|
|
|
Indentation is not (completely) arbitrary. There are three steps,
|
|
the first of which need be done only once per editing session.
|
|
|
|
- Make sure you evaluate *all* `defmacro' forms so that Emacs knows
|
|
about each form's indentation spec (if any).
|
|
|
|
- Use C-M-q at top-level open-paren to canonicalize indentation.
|
|
|
|
- Apply stylistic exceptions (manual override). Common cases:
|
|
- `flet', `labels', `macrolet' -- Emacs does a poor job here, indenting
|
|
too much, so overriding it is almost a requirement (many examples);
|
|
- deliberate flush-left (to column 0) so that C-M-x "continues to work"
|
|
on an inner form (eg: dvc-capturing-lambda);
|
|
- end-of-line ";;"-comment alignment (eg: defstruct dvc-fileinfo-file).
|
|
|
|
|
|
Process management
|
|
==================
|
|
|
|
The function dvc--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 either
|
|
Bazaar or Git to clone the latest repo.
|
|
|
|
Programs for maintainers:
|
|
(required) autoconf, tar, gzip, makeinfo
|
|
(optional) texi2dvi, etags
|
|
|
|
With the exception of gzip (which is invoked simply as "gzip"),
|
|
the invocation of each of these programs is influenced by a
|
|
makefile variable of the same name, but all upcased. For example,
|
|
you can choose a different tar for "make dist" using the command:
|
|
make dist TAR=/path/to/my/tar
|
|
The default values for these variables is simply the program name.
|
|
|
|
Historical note: We used to AC_PATH_PROG them in configure.ac, but
|
|
that did not benefit the end user (./configure && make all install),
|
|
so we stopped mid-2008.
|
|
|
|
* Official releases
|
|
-------------------
|
|
|
|
Official releases will be made by the release manager, after
|
|
discussion on the mailing list.
|
|
|
|
The release manager will modify configure.ac to set the second
|
|
arg of AC_INIT to 1.1, for example, and then type the commands
|
|
|
|
autoreconf
|
|
./configure (or ./config.status --recheck)
|
|
make
|
|
make dist
|
|
|