view doc/runrst @ 28429:a47881680402

rebase: turn rebaseskipobsolete on by default

Consider the following use case. User has a set of commits he wants to rebase
onto some destination. Some of the commits in the set are already rebased
and their new versions are now among the ancestors of destination. Traditional
rebase behavior would make the rebase and effectively try to apply older
versions of these commits on top of newer versions, like this:

    a` --> b --> a`

(where both 'a`' and 'a``' are rebased versions of 'a')

This is not desired since 'b' might have made changes to 'a`' which can now
result in merge conflicts. We can avoid these merge conflicts since we know
that 'a``' is an older version of 'a`', so we don't even need to put it on top
of 'b'. Rebaseskipobsolete allows us to do exactly that.

Another undesired effect of a pure rebase is that now 'a`' and 'a``' are both
successors to 'a' which is a divergence. We don't want that and not rebasing
'a' the second time allows to avoid it.

This was not enabled by default initially because we wanted to have some more
experience with it. After months of painless usages in multiple places, we are
confident enough to turn it on my default.

#!/usr/bin/env python
#
# runrst - register custom roles and run correct writer
#
# Copyright 2010 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.

"""usage: %s WRITER args...

where WRITER is the name of a Docutils writer such as 'html' or 'manpage'
"""

import sys
try:
    from docutils.parsers.rst import roles
    from docutils.core import publish_cmdline
    from docutils import nodes, utils
except ImportError:
    sys.stderr.write("abort: couldn't generate documentation: docutils "
                     "module is missing\n")
    sys.stderr.write("please install python-docutils or see "
                     "http://docutils.sourceforge.net/\n")
    sys.exit(-1)

def role_hg(name, rawtext, text, lineno, inliner,
            options={}, content=[]):
    text = "hg " + utils.unescape(text)
    linktext = nodes.literal(rawtext, text)
    parts = text.split()
    cmd, args = parts[1], parts[2:]
    refuri = "hg.1.html#%s" % cmd
    if cmd == 'help' and args:
        if args[0] == 'config':
            # :hg:`help config`
            refuri = "hgrc.5.html"
        elif args[0].startswith('config.'):
            # :hg:`help config.SECTION...`
            refuri = "hgrc.5.html#%s" % args[0].split('.', 2)[1]
        elif len(args) >= 2 and args[0] == '-c':
            # :hg:`help -c COMMAND ...` is equivalent to :hg:`COMMAND`
            # (mainly for :hg:`help -c config`)
            refuri = "hg.1.html#%s" % args[1]
        else:
            refuri = "hg.1.html#%s" % args[0]
    node = nodes.reference(rawtext, '', linktext,
                           refuri=refuri)
    return [node], []

roles.register_local_role("hg", role_hg)

if __name__ == "__main__":
    if len(sys.argv) < 2:
        sys.stderr.write(__doc__ % sys.argv[0])
        sys.exit(1)

    writer = sys.argv[1]
    del sys.argv[1]

    publish_cmdline(writer_name=writer)