-# we need at least an empty module to make build scripts realize the
-# dependency is present, apparently
+# nothing to see here, move along!
+Alien::hg -- The Mercurial DVCS, packaged for the CPAN
+ use Alien::hg::ConfigData;
+ my $hg_binary = Alien::hg::ConfigData->config('which_hg');
+ system($hg_binary, 'commit');
+This distribution is a re-packaging of the Mercurial DVCS for the CPAN.
+After installing it, you should be able to get a valid path to an
+F<hg> binary, independently of how it got installed onto your system.
+=head2 OUR BUILD PROCESS
+There's basically three steps:
+=item 1. Guess whether F<hg> is already present.
+This step tries to find a binary called F<hg> in your PATH. If it is
+present, it tries calling
+to determine if that's actually Mercurial or some other tool also
+called F<hg>. If that works and a version number can be extracted
+from the output, the user is asked whether she would like to use that
+version or proceed with the installation of a brand-new Mercurial.
+If that binary is actually an L<Alien::hg> wrapper from a previous
+installation, answering "y" will lead to trouble. The default is "n"
+("no, fetch and install a separate Mercurial").
+If no F<hg> binary has been found, the installation proceeds to the
+next step, no questions asked.
+=item 2. Fetch and install Mercurial.
+This only occurs if you answered "no" in the previous step, or if no
+F<hg> binary has been found.
+This step fetches the most recent stable release of Mercurial, for
+installation into a L<File::ShareDir>-compatible directory. This step
+should B<never> overwrite a version of Mercurial that's been installed
+through regular means (manually from the tarball, or from your
+favorite package manager -- I mean your favorite package manager
+that's not a CPAN client).
+When this step is completed, the user is asked whether a wrapper
+around the new Mercurial install should be installed into her PATH.
+If that overwrites your previously installed Mercurial binary, you
+should probably answer "no" (but that should never happen for
+L<perlbrew|App::perlbrew> setups... you are using perlbrew, right?).
+The default is "n" (don't install the wrapper).
+=item 3. Install the wrapper.
+This only occurs if you answered "yes" in the previous step. The
+wrapper is a tiny script that just C<exec>s the C<which_hg> key of
+L<Alien::hg::ConfigData>, which should be pointing at the new
+Mercurial if everything has gone OK.
+L<Alien::hg::ConfigData> is produced by L<Module::Build>, and the only
+value of interest in there should be:
+ my $hg = Alien::hg::ConfigData->config('which_hg');
+which is an absolute path to a working F<hg> binary (not the wrapper,
+the real Python one -- either the one you just installed, or the one
+you had installed before).
+There are none. This is a documentation-only package.
+Fabrice Gabolde <firstname.lastname@example.org>
+=head1 COPYRIGHT AND LICENSE
+This software is copyright (c) 2013 by Fabrice Gabolde.
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+Mercurial itself is copyrighted by Matt Mackall and others, and is
+licensed under the terms of the GPLv2+.