I have found Doc/make.bat to be very useful, but I have hit a few of its limitations now and then.  Thus, I have made extensive modifications to bring it much closer to the way Doc/Makefile works.  Among the things changed in the attached patch:

- Use pushd/popd to make sure everything is done in the Doc directory.

- Allow variables to be set on the command line, e.g.:
       make html "PYTHON2=python"

- Set PYTHON2 and PYTHON3 variables separately; the Sphinx version and associated tools we're currently using want Python 2, which defaults to "py -2".  Other tools, like Tools/scripts/serve.py (the make serve target), expect Python 3; setting the default PYTHON3 searches for python(_d).exe in PCbuild(\amd64), and falls back to "py -3" if not found.

- Set the HTML Help Workshop default path to %ProgramFiles(x86)%\..., if that variable is defined. (If I understand correctly, that variable is only defined on x64 installations, and in cases where it is not defined on x64, %ProgramFiles% silently copies %ProgramFiles(x86)%.)

- Convert target choice to a single for loop, rather than several lines of if.  Anything not in the list falls through to the help message.

- Expand the help message to match the message given by Doc/Makefile

- Add the "clean" target, which does the same as Makefile

- Reimplement "update" to match Makefile (call clean, call checkout.  I do wonder if maybe it should be done the other way around, though; reimplement Makfile's "update" target to simply update the svn checkouts, rather than re-pull them)

- Add separate labels for each target.  The old method of sending everything to :build was very clever and kept the file short, but limited flexibility.  It's also nice to get a message at the end (matching Makefile), which is much easier to do with separate labels.

- Add support for the PAPER environment variable in LaTeX building.

- Add coverage, doctest, pydoc-topics, dist, check, and serve targets.  "dist" cannot be completed in the same way with default tools on Windows, so all it does is build html, text, latex (a4 and letter), and epub and copy them into the dist directory.

- checkout checks for the existence of the checked out packages before checking out

- build calls checkout before building, so you can go right to "make html" instead of having to do "make checkout && make html"

- Add support for SOURCES and SPHINXOPTS environment variables.

Everything seems to work for me, but I've only been able to test on Windows 7 (32 and 64 bit).  I don't believe there's anything in there that doesn't exist in XP, though.  Also, since this version of the file has a lot of labels, this patch does somewhat rely on resolution of issue 17202.  It should probably work without any changes to .hgeol, but that can't be guaranteed.

There are a couple of drawbacks to the patched version; it's a much longer file, and it does lose a good chunk of the elegance of the original solution.  If anyone has any suggestions for regaining some of that elegance without losing any of the functionality, I am of course all ears :). In particular, I'm not a huge fan of having to have "pushd ." at the beginning of every label, but the only other solutions I came up with involved setting and unsetting a "DISALLOW_POPD" variable in several places, and a condition on the popd at :end, or forgetting the pushd/popd thing entirely.

I'm looking forward to hearing what anyone else thinks of this, positive or negative :)