[darcs-users] Ideal authorsfile syntax and semantics.

Trent W. Buck trentbuck at gmail.com
Sun Mar 15 01:44:18 UTC 2009


Simon Michael <simon at joyful.com> writes:

> PS as a separate/alternate exercise, perhaps you'd like to document
> the idealised version of this feature - you can change how it works if
> it makes the docs shorter and clearer - and if it's not too costly I
> could try to implement that. An experiment in doc-driven development.

I've been thinking about this, and here's how I would do it.  In this
post display-name, addr-spec etc. are parsers defined in RFC 2822.

By default _darcs/prefs/authors is used.  You can use a
version-controlled file using "darcs setpref authorsfile".

Syntax
======

File is line based.  Comments are blank lines or start with an
octothorpe.  Other lines have a display-name, a colon, then one or more
addr-spec.

Example:

    # This is a comment
       # So is this
    David Roundy: droundy at darcs.net droundy at abridgegame.org droundy at civet.berkeley.edu
    Eric Kow: kowey at darcs.net kow at loria.fr eric.kow at gmail.com eric.kow at loria.fr E.Y.Kow at brighton.ac.uk

Note that display-name allows for colons in its quoted-string format.


Semantics
=========

The canonical name is "x <y>" where x is the display-name and y is the
first addr-spec.

Each patch has an author string.  This is parsed as name-addr, and the
addr-spec part extracted.  (If it fails to parse as name-addr, that
patch is not changed).  Next, a case-insensitive *string* comparison is
made between the addr-spec from the patch, and those from authorsfile.
If they match *exactly*, then the patch's author string is replaced with
the canonical name.  For full marks, this ought to be done everywhere,
not just in "darcs show authors".

For example, with the above the above,

 - A bare "kowey at darcs.net" becomes "Eric Kow <kowey at darcs.net>".
 - "Misspelt <kow at loria.fr>" becomes "Eric Kow <kowey at darcs.net>".

 - "Fred <notkowey at darcs.net>" is unchanged, because
   "notkowey at darcs.net" is not case-insensitively equal to
   "kowey at darcs.net".

 - "David Roundy" would not be changed, as it doesn't parse as a
   name-addr.


Analysis
========

Pros: display-name is more flexible.  Doesn't pollute the root working
tree by default.  No false positives (e.g. we no longer allow just
matching "fred@").  Less punctuation (<>) hopefully makes the file
easier to read.

Cons: someone has to code it.  add-spec still can't contain whitespace
and other silly things that RFC 2822 technically allows.  Because exact
matching is used, "fred@" needs to be expanded into all the actual
addresses.



More information about the darcs-users mailing list