[darcs-users] darcs patch: Refactor "darcs apply" short description. (and 6 more)

Simon Michael simon at joyful.com
Sat Mar 14 20:39:50 UTC 2009

Hi Trent, thanks for your show authors docs cleanup (extracted below.) I 
think some precision was added but also some was lost. I can't help but 
try to tweak it further:

> hunk ./src/Darcs/Commands/ShowAuthors.lhs 41
> - "The authors command writes a list of all patch authors in the repository to\n" ++
> - "standard output.\n" ++
> + "The `darcs show authors' command lists the authors of the current\n" ++
> + "repository, sorted by the number of patches contributed.  With the\n" ++
> + "--verbose option, this command simply lists the author of each patch\n" ++
> + "(without aggregation or sorting).\n"
>   "\n" ++


> hunk ./src/Darcs/Commands/ShowAuthors.lhs 46
> - "Canonical author spellings can be defined in an .authorspellings file.\n" ++
> - "Each line contains one or more comma-separated fields: the canonical\n" ++
> - "name and angle-bracketed email address, optionally followed by\n" ++
> - "additional regular expression patterns. An author string which\n" ++
> - "contains the canonical email address or any of the patterns will be\n" ++
> - "replaced by the full canonical form.  All matching is case-insensitive.\n" ++
> - "To match the whole author string use ^ and $. Blank lines and lines\n" ++
> - "beginning with -- are ignored.\n"
> -
> + "By default authors with multiple email addresses are treated as\n" ++
> + "separate individuals, and the contributions are listed separately.\n" ++
> + "However if a file `.authorspellings' exists in the root of the working\n" ++
> + "tree, Darcs will use it to determine the `canonical' email address of\n" ++
> + "such authors, and list all their contributions as a single entry.\n" ++
> + "\n" ++

It's not just for the email address, but to correct mispellings, missing 
character accents, missing full names etc. How about:

"Often, a repository contains multiple variations of an author's name or 
email address. If a file `.authorspellings' exists in the root of the 
working tree, Darcs will use it to recognize and convert these variants 
to a canonical name and email address, ensuring a single accurate entry 
in the `show authors' report (only; other commands are currently not 

> + "An .authorspellings file is a sequence of lines separated by the\n" ++
> + "newline character (i.e. LF, not CRLF).  Lines beginning with two\n" ++
> + "hyphens, or containing only whitespace, are ignored.  Other lines must\n" ++
> + "begin with an author's canonical email address (which may not contain\n" ++
> + "a comma).  It may be followed by a comma and one or more extended\n" ++
> + "regular expressions, delimited by commas.\n" ++
> + "\n" ++
> + "If a patch's author string matches any regex, it is replaced by the\n" ++
> + "canonical address listed at the start of the line.  If the canonical\n" ++
> + "address consists of a full name followed by an email address in angle\n" ++
> + "brackets, string (not regex) matching is also done against the address\n" ++
> + "in angle brackets.  All matching is case-insensitive.\n" ++
> + "\n" ++
> + "Only the output of `darcs show authors' is affected by the presence of\n" ++
> + "an .authorspellings file; other commands (such as `darcs changes')\n" ++
> + "currently ignore this file.\n" ++
> + "\n" ++

The original was concise and I like it a little better than the above. 
Instead, what do you think of:

"The .authorspellings file is a sequence of lines (which currently must 
be separated by unix-style newline, not CRLF.) Each line defines the 
canonical spelling for an author, which will appear in the show authors 
report. Typically this is "Full Name <email at address>" without the 
quotes; it may not contain a comma. Following this, there may be a comma 
and one or more extended regular expressions, delimited by commas.

If a patch's author string matches (a) the canonical email address..."

oh frick I don't remember what the implementation does and I'm out of 
time here.

> + "An example .authorspelling file is:\n" ++
> + "\n" ++
> + "    -- This is a comment.\n" ++
> + "    Fred Nurk <fred at example.com>\n" ++
> + "    John Snagge <j.snagge at bbc.co.uk>, snagge@, john at pobox.com\n" ++
> + "    eccles at smithsonian.museum ("Mad" Dan Eccles), eccles@(si.edu|pobox.com)\n"

The example is good. The third line indeed works but I would omit it and 
show only the "First Last <email>" convention, to keep things simple.

More information about the darcs-users mailing list