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" ++
good
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
affected)."
+ "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 <em...@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 <[email protected]>\n" ++
+ " John Snagge <[email protected]>, snagge@, [email protected]\n" ++
+ " [email protected] ("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.
_______________________________________________
darcs-users mailing list
[email protected]
http://lists.osuosl.org/mailman/listinfo/darcs-users
