Re: arch taglines for emacs

[Tom Lord]

    > From: Richard Stallman <address@hidden>

    >   > From: Miles Bader <address@hidden>

    >   > I think this behavior is dangerous because whitespace and comment
    >   > delimiters can get changed inadvertently, whereas users are more 
likely
    >   > to be careful about the actual tag string (which looks `magic').

    >     That's fine, although no problems have ever been reported in practice.

    > Could you tell me what is the issue here?  I have not received Miles'
    > message that you are replying to.  Was it sent to emacs-devel?


One of the cornerstones of arch are the tools `mkpatch' and `dopatch'
which are generalizations of `diff' and `patch'.    Rather than
comparing two versions of a single file or patching a single file,
`mkpatch' and `dopatch' work on an entire source tree.

Among the "differences" noted by `mkpatch' are names of files and
directories.   For example, if I have two versions of the hello world
program:

        version-1 tree:

                ./Makefile
                ./hw.c


        version-2 tree:

                ./Makefile
                ./hw.c.~1~
                ./hello.c       # used to be called hw.c

`mkpatch' will produce a changeset that says (in effect):

        hw.c has been renamed hello.c
        hello.c has been modified (here are the diffs....)

So arch needs _some_ mechanism to recognize that in the two trees,
"hw.c" and "hello.c" are the same logical file.

Two mechanisms are provided.  In one mechanism, extra files are
added to the tree (stored in subdirs named `.arch-ids') which describe
the logical identities of files.   In another mechanism, a specially 
formatted comment is added _inside_ of each file, and arch searches
for those.   (In practice a mixture of these is often used, since
though the special comments are more convenient, they can't be applied
to all types of files.)

The special comments method is usually the most convenient.   When
such comments are used, a user can rename a file in the usual way
(e.g., with `mv(1)') and arch recognizes what has happened.   When
external records are used, moving a file requires an extra step to
update the external record (e.g., the arch `move' command).

In the case of Emacs, where only a subset of the developers will be
using arch, the special comments method is arguably the best choice.
Developers not using arch can simply ignore these comments -- they
only have to remember not to change them.  (External files are still
desirable to assign logical names to directories, but because of the
way those files are stored, users do _not_ have to use the arch `move'
command when renaming a directory.)

The issue Miles is raising concerns the syntax of the special
comments.  Given a comment such as:


        /* arch-tag: this is the tag i chose for this file. */

arch forms a string which stands for the logical name of the file.
To form this string, it takes the entire contents of the string
following "arch-tag:", strips surrounding whitespace, and replaces
other non-graphical characters with "_".   So, the logical name of
that file is:

        this_is_the_tag_i_chose_for_this_file._*/

Miles is concerned that a seemingly harmless change, like adding extra
whitespace, will have the undesirable side effect of changing the
logical name of the file:

      modified comment:

        /* arch-tag: this is the tag i chose for this file.
         */

      new logical file name:

        this_is_the_tag_i_chose_for_this_file.


Such problems have not been observed in practice, but I agree with
Miles that it is a legitimate concern.  So he proposed a change to the
way logical names are formed and I've pointed out (on another list)
some design constraints that his first proposal doesn't satisfy.  (The
primary constraint is that any change in this area should be made in a
way that is 100% upward compatible will all already existing
mkpatch-generated changesets.  Miles' first proposal was based on a
solution that in theory might be incomatible with some changesets, but
that he guesses will be compatible with all of them in practice.)

Meanwhile, there is an easy convention to adopt that will make 
such problems unlikely to occur in the Emacs source and will 
make it easy to upgrade to a new syntax if we decide to add one to
arch.   The convention is to use tags which do not contain spaces:


        /* arch-tag: d41d8cd98f00b204e9800998ecf8427e
         */

or

        /* arch-tag: d41d8cd98f00b204e9800998ecf8427e
         * Do not Modify this comment.
         */

or similar.

-t