[Suggested in issue5095 by John Machin]

The 2.6.1 documentation consists of a *single* line:
"distutils.command.bdist_msi — Build a Microsoft Installer binary
package". The docs should explain briefly what an msi file is, and why a
packager might want to use it instead of wininst.

Can you propose specific wording?

If no one beats me to it, I plan to do this at PyCon.

I'm thinking of stealing/condensing some of the text from here:
http://www.dcl.hpi.uni-potsdam.de/home/loewis/msipackage.html

Does that seem okay? Is any of that text no longer accurate? (E.g. does
bdist_wininst now support Win64?)

That should all be correct still (except that the status has advanced); 
using it for the documentation is fine. It's just that it is more 
rationale than specification.

The original docs request was for a rationale for using bdist_msi
instead of bdist_wininst, but you're right there should be something at
least a little specification-y. And we probably want to keep it pretty
short, so maybe something like::

  .. class: distutils.command.build_bdist_msi.bdist_msi(Command)

     Builds a `Microsoft Installer`_ (.msi) binary package.

     .. _Microsoft Installer:
     http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx

     In most cases, the bdist_msi installer is a better choice than the 
     bdist_wininst installer, because it provides better support for 
     Win64 platforms, allows administrators to perform non-interactive
     installations, and allows installation through group policies.

I'm on the fence as to whether or not to include the URL to the MSI
info. That's probably as close to a specification as we can get, but
it's probably unnecessary for 99% of the people who might read the
bdist_msi docs.

I'll wait for a patch from you, Steven.

Here you go. I built the docs with the attached patch, and everything
looks about right to me now.

Committed in r70905.