i18n/hggettext

wix: functionality to automate building WiX installers

Like we did for Inno Setup, we want to make it easier to
produce WiX installers. This commit does that.

We introduce a new hgpackaging.wix module for performing
all the high-level tasks required to produce WiX installers.
This required miscellaneous enhancements to existing code in
hgpackaging, including support for signing binaries.

A new build.py script for calling into the module APIs has been
created. It behaves very similarly to the Inno Setup build.py
script.

Unlike Inno Setup, we didn't have code in the repo previously
to generate WiX installers. It appears that all existing
automation for building WiX installers lives in the
https://bitbucket.org/tortoisehg/thg-winbuild repository - most
notably in its setup.py file. My strategy for inventing the
code in this commit was to step through the code in that repo's
setup.py and observe what it was doing. Despite the length of
setup.py in that repository, the actual amount of steps required
to produce a WiX installer is actually quite low. It consists
of a basic py2exe build plus invocations of candle.exe and
light.exe to produce the MSI.

One rabbit hole that gave me fits was locating the Visual Studio
9 C Runtime merge modules. These merge modules are only present
on your system if you have a full Visual Studio 2008 installation.
Fortunately, I have a copy of Visual Studio 2008 and was able
to install all the required updates. I then uploaded these merge
modules to a personal repository on GitHub. That is where the
added code references them from. We probably don't need to
ship the merge modules. But that is for another day.

The installs from the MSIs produced with the new automation
differ from the last official MSI in the following ways:

* Our HTML manual pages have UNIX line endings instead of Windows.
* We ship modules in the mercurial.pure package. It appears the
  upstream packaging code is not including this package due to
  omission (they supply an explicit list of packages that has
  drifted out of sync with our setup.py).
* We do not ship various distutils.* modules. This is because
  virtualenvs have a custom distutils/__init__.py that automagically
  imports distutils from its original location and py2exe gets
  confused by this. We don't use distutils in core Mercurial and
  don't provide a usable python.exe, so this omission should be
  acceptable.
* The version of the enum package is different and we ship
  an enum.pyc instead of an enum/__init__.py.
* The version of the docutils package is different and we
  ship a different set of files.
* The version of Sphinx is drastically newer and we ship a
  number of files the old version did not. (I'm not sure why
  we ship Sphinx - I think it is a side-effect of the way the
  THG code was installing dependencies.)
* We ship the idna package (dependent of requests which is a
  dependency of newer versions of Sphinx).
* The version of imagesize is different and we ship an
  imagesize.pyc instead of an imagesize/__init__.pyc.
* The version of the jinja2 package is different and the sets
  of files differs.
* We ship the packaging package, which is a dependency for Sphinx.
* The version of the pygments package is different and the sets
  of files differs.
* We ship the requests package, which is a dependency for Sphinx.
* We ship the snowballstemmer package, which is a dependency for
  Sphinx.
* We ship the urllib3 package, which is a dependency for requests,
  which is a dependency for Sphinx.
* We ship a newer version of the futures package, which includes a
  handful of extra modules that match Python 3 module names.

# no-check-commit because foo_bar naming

Differential Revision: https://phab.mercurial-scm.org/D6097

#!/usr/bin/env python
#
# hggettext - carefully extract docstrings for Mercurial
#
# Copyright 2009 Matt Mackall <[e-mail]> and others
#
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.

# The normalize function is taken from pygettext which is distributed
# with Python under the Python License, which is GPL compatible.

"""Extract docstrings from Mercurial commands.

Compared to pygettext, this script knows about the cmdtable and table
dictionaries used by Mercurial, and will only extract docstrings from
functions mentioned therein.

Use xgettext like normal to extract strings marked as translatable and
join the message cataloges to get the final catalog.
"""

from __future__ import absolute_import, print_function

import inspect
import os
import re
import sys


def escape(s):
    # The order is important, the backslash must be escaped first
    # since the other replacements introduce new backslashes
    # themselves.
    s = s.replace('\\', '\\\\')
    s = s.replace('\n', '\\n')
    s = s.replace('\r', '\\r')
    s = s.replace('\t', '\\t')
    s = s.replace('"', '\\"')
    return s


def normalize(s):
    # This converts the various Python string types into a format that
    # is appropriate for .po files, namely much closer to C style.
    lines = s.split('\n')
    if len(lines) == 1:
        s = '"' + escape(s) + '"'
    else:
        if not lines[-1]:
            del lines[-1]
            lines[-1] = lines[-1] + '\n'
        lines = map(escape, lines)
        lineterm = '\\n"\n"'
        s = '""\n"' + lineterm.join(lines) + '"'
    return s


def poentry(path, lineno, s):
    return ('#: %s:%d\n' % (path, lineno) +
            'msgid %s\n' % normalize(s) +
            'msgstr ""\n')

doctestre = re.compile(r'^ +>>> ', re.MULTILINE)

def offset(src, doc, name, lineno, default):
    """Compute offset or issue a warning on stdout."""
    # remove doctest part, in order to avoid backslash mismatching
    m = doctestre.search(doc)
    if m:
        doc = doc[:m.start()]

    # Backslashes in doc appear doubled in src.
    end = src.find(doc.replace('\\', '\\\\'))
    if end == -1:
        # This can happen if the docstring contains unnecessary escape
        # sequences such as \" in a triple-quoted string. The problem
        # is that \" is turned into " and so doc wont appear in src.
        sys.stderr.write("%s:%d:warning:"
                         " unknown docstr offset, assuming %d lines\n"
                         % (name, lineno, default))
        return default
    else:
        return src.count('\n', 0, end)


def importpath(path):
    """Import a path like foo/bar/baz.py and return the baz module."""
    if path.endswith('.py'):
        path = path[:-3]
    if path.endswith('/__init__'):
        path = path[:-9]
    path = path.replace('/', '.')
    mod = __import__(path)
    for comp in path.split('.')[1:]:
        mod = getattr(mod, comp)
    return mod


def docstrings(path):
    """Extract docstrings from path.

    This respects the Mercurial cmdtable/table convention and will
    only extract docstrings from functions mentioned in these tables.
    """
    mod = importpath(path)
    if not path.startswith('mercurial/') and mod.__doc__:
        with open(path) as fobj:
            src = fobj.read()
        lineno = 1 + offset(src, mod.__doc__, path, 1, 7)
        print(poentry(path, lineno, mod.__doc__))

    functions = list(getattr(mod, 'i18nfunctions', []))
    functions = [(f, True) for f in functions]

    cmdtable = getattr(mod, 'cmdtable', {})
    if not cmdtable:
        # Maybe we are processing mercurial.commands?
        cmdtable = getattr(mod, 'table', {})
    functions.extend((c[0], False) for c in cmdtable.itervalues())

    for func, rstrip in functions:
        if func.__doc__:
            docobj = func # this might be a proxy to provide formatted doc
            func = getattr(func, '_origfunc', func)
            funcmod = inspect.getmodule(func)
            extra = ''
            if funcmod.__package__ == funcmod.__name__:
                extra = '/__init__'
            actualpath = '%s%s.py' % (funcmod.__name__.replace('.', '/'), extra)

            src = inspect.getsource(func)
            lineno = inspect.getsourcelines(func)[1]
            doc = docobj.__doc__
            origdoc = getattr(docobj, '_origdoc', '')
            if rstrip:
                doc = doc.rstrip()
                origdoc = origdoc.rstrip()
            if origdoc:
                lineno += offset(src, origdoc, actualpath, lineno, 1)
            else:
                lineno += offset(src, doc, actualpath, lineno, 1)
            print(poentry(actualpath, lineno, doc))


def rawtext(path):
    with open(path) as f:
        src = f.read()
    print(poentry(path, 1, src))


if __name__ == "__main__":
    # It is very important that we import the Mercurial modules from
    # the source tree where hggettext is executed. Otherwise we might
    # accidentally import and extract strings from a Mercurial
    # installation mentioned in PYTHONPATH.
    sys.path.insert(0, os.getcwd())
    from mercurial import demandimport; demandimport.enable()
    for path in sys.argv[1:]:
        if path.endswith('.txt'):
            rawtext(path)
        else:
            docstrings(path)