project: for consistency, also separate alias authors with pipes.

[update-copyright.git] / README

diff --git a/README b/README
index 674e039fcd18afed4b4f75510c5303ceb2fcfeb0..5d2e3ff28f3d7e80e56aec807894e016f9e613eb 100644 (file)
--- a/README
+++ b/README
@@ -1,3 +1,5 @@
+.. -*- coding: utf-8 -*-
+
 ``update-copyright`` is an automatic copyright updating tool.  I wrote
 the original for `Bugs Everywhere`_, but ended up copying it into a
 number of my projects.  Copying is bad, so here it is, split out as
@@ -38,7 +40,7 @@ Installing by hand
 See the homepage_ for details.  To install the checkout, run the
 standard::
 
-    $ python setup.py install
+  $ python setup.py install
 
 Usage
 =====
@@ -114,12 +116,54 @@ is replaced by a new blurb, which is automatically generated from your
 configured long copyright string, with author names and edit years
 extracted from the VCS data for that file.
 
+While the above works well for languages that use ``#`` to mark
+comment lines, it doesn't work for languages like C that use ``/*…*/``
+to mark comments.  There blurb-update algorithm also looks for any
+lines that begging with ``/* Copyright`` and replaces that line, and
+subsequent lines up to one beginning with `` */``, with a new blurb.
+
+Because I've never seen a file with *both* trigger lines, it shouldn't
+be a problem to run both against each of your versioned files.  If it
+is a problem for you, let me know, and we can add some configuration
+options to work around the problem.
+
+Incomplete VCS history
+----------------------
+
+Sometimes files have authors or alterations not recorded in a
+project's VCS history.  You can use the ``author-hacks`` section to
+add authors to a file, and the ``year-hacks`` section to adjust the
+files original year.  Author names should be pipe-separated.  For
+example::
+
+  [author-hacks]
+  path/to/file: John Doe <jdoe@a.com> | Jane Smith <jsmith@b.net>
+
+  [year-hacks]
+  path/to/another/file: 2009
+
+Add entries for as many files as you like.  Paths should be relative
+to your project root.  Always use forward slashes (``/``) to separate
+path elements.
+
+Aliases
+-------
+
+Occasionally names or email addresses used when committing to the VCS
+will go out of date.  Some VCSs have a built-in method of dealing with
+this (e.g. Git's .mailmap_).  For those without such a VCS, you can
+add an `aliases`` section to your config file, where the option names
+are the canonical name of the ...?.  For example::
+
+  [aliases]
+  John Doe <jdoe@a.com>: John Doe | jdoe | J. Doe <j@doe.net>
+
 Testing
 =======
 
 Run the internal unit tests with::
 
-    $ nosetests --with-doctest --doctest-tests update_copyright
+  $ nosetests --with-doctest --doctest-tests update_copyright
 
 Licence
 =======
@@ -131,17 +175,18 @@ Author
 ======
 
 W. Trevor King
-wking@drexel.edu
+wking@tremily.us
 
 
 .. _Bugs Everywhere: http://bugseverywhere.org/
 .. _Gentoo: http://www.gentoo.org/
 .. _layman: http://layman.sourceforge.net/
-.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay
+.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 .. _Git: http://git-scm.com/
 .. _homepage: http://blog.tremily.us/posts/update-copyright/
 .. _RawConfigParser:
   http://docs.python.org/dev/library/configparser.html#configparser.RawConfigParser
 .. _syntax documentation:
   http://docs.python.org/dev/library/configparser.html#supported-ini-file-structure
+.. _.mailmap: http://schacon.github.com/git/git-shortlog.html#_mapping_authors
 .. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html