Use hg role in help strings

hgext/bookmarks.py

@@ -88,10 +88,10 b' def bookmark(ui, repo, mark=None, rev=No'
 
     Bookmarks are pointers to certain commits that move when
     committing. Bookmarks are local. They can be renamed, copied and
-    deleted. It is possible to use bookmark names in 'hg merge' and
-    'hg update' to merge and update respectively to a given bookmark.
+    deleted. It is possible to use bookmark names in :hg:`merge` and
+    :hg:`update` to merge and update respectively to a given bookmark.
 
-    You can use 'hg bookmark NAME' to set a bookmark on the working
+    You can use :hg:`bookmark NAME` to set a bookmark on the working
     directory's parent revision with the given name. If you specify
     a revision using -r REV (where REV may be an existing bookmark),
     the bookmark is assigned to that revision.

hgext/fetch.py

@@ -28,7 +28,7 b" def fetch(ui, repo, source='default', **"
     parent, with local changes as the second. To switch the merge
     order, use --switch-parent.
 
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    See :hg:`help dates` for a list of formats valid for -d/--date.
     '''
 
     date = opts.get('date')

hgext/keyword.py

@@ -49,25 +49,25 b' NOTE: the more specific you are in your '
 lose speed in huge repositories.
 
 For [keywordmaps] template mapping and expansion demonstration and
-control run "hg kwdemo". See "hg help templates" for a list of
+control run :hg:`kwdemo`. See :hg:`help templates` for a list of
 available templates and filters.
 
 An additional date template filter {date|utcdate} is provided. It
 returns a date like "2006/09/18 15:13:13".
 
-The default template mappings (view with "hg kwdemo -d") can be
-replaced with customized keywords and templates. Again, run "hg
-kwdemo" to control the results of your config changes.
+The default template mappings (view with :hg:`kwdemo -d`) can be
+replaced with customized keywords and templates. Again, run
+:hg:`kwdemo` to control the results of your config changes.
 
-Before changing/disabling active keywords, run "hg kwshrink" to avoid
+Before changing/disabling active keywords, run :hg:`kwshrink` to avoid
 the risk of inadvertently storing expanded keywords in the change
 history.
 
 To force expansion after enabling it, or a configuration change, run
-"hg kwexpand".
+:hg:`kwexpand`.
 
 Also, when committing with the record extension or using mq's qrecord,
-be aware that keywords cannot be updated. Again, run "hg kwexpand" on
+be aware that keywords cannot be updated. Again, run :hg:`kwexpand` on
 the files in question to update keyword expansions after all changes
 have been checked in.
 
@@ -361,7 +361,7 b' def files(ui, repo, *pats, **opts):'
     execution by including only files that are actual candidates for
     expansion.
 
-    See "hg help keyword" on how to construct patterns both for
+    See :hg:`help keyword` on how to construct patterns both for
     inclusion and exclusion of files.
 
     With -A/--all and -v/--verbose the codes used to show the status
@@ -398,7 +398,7 b' def shrink(ui, repo, *pats, **opts):'
     '''revert expanded keywords in the working directory
 
     Run before changing/disabling active keywords or if you experience
-    problems with "hg import" or "hg merge".
+    problems with :hg:`import` or :hg:`merge`.
 
     kwshrink refuses to run if given files contain local changes.
     '''

hgext/mq.py

@@ -14,7 +14,7 b' applied patches (subset of known patches'
 Known patches are represented as patch files in the .hg/patches
 directory. Applied patches are both patch files and changesets.
 
-Common tasks (use "hg help command" for more details)::
+Common tasks (use :hg:`help command` for more details)::
 
   create new patch                          qnew
   import existing patch                     qimport
@@ -2041,9 +2041,9 b' def diff(ui, repo, *pats, **opts):'
     last refresh (thus showing what the current patch would become
     after a qrefresh).
 
-    Use 'hg diff' if you only want to see the changes made since the
-    last qrefresh, or 'hg export qtip' if you want to see changes made
-    by the current patch without including changes made since the
+    Use :hg:`diff` if you only want to see the changes made since the
+    last qrefresh, or :hg:`export qtip` if you want to see changes
+    made by the current patch without including changes made since the
     qrefresh.
     """
     repo.mq.diff(repo, pats, opts)

hgext/pager.py

@@ -45,8 +45,8 b' paged.'
 
 If pager.attend is present, pager.ignore will be ignored.
 
-To ignore global commands like "hg version" or "hg help", you have to
-specify them in the global .hgrc
+To ignore global commands like :hg:`version` or :hg:`help`, you have
+to specify them in the global .hgrc
 '''
 
 import sys, os, signal

hgext/patchbomb.py

@@ -16,7 +16,7 b' message contains two or three body parts'
 
 - The changeset description.
 - [Optional] The result of running diffstat on the patch.
-- The patch itself, as generated by "hg export".
+- The patch itself, as generated by :hg:`export`.
 
 Each message refers to the first in the series using the In-Reply-To
 and References headers, so they will show up as a sequence in threaded
@@ -38,11 +38,11 b' file::'
 Use ``[patchbomb]`` as configuration section name if you need to
 override global ``[email]`` address settings.
 
-Then you can use the "hg email" command to mail a series of changesets
-as a patchbomb.
+Then you can use the :hg:`email` command to mail a series of
+changesets as a patchbomb.
 
 To avoid sending patches prematurely, it is a good idea to first run
-the "email" command with the "-n" option (test only). You will be
+the :hg:`email` command with the "-n" option (test only). You will be
 prompted for an email recipient address, a subject and an introductory
 message describing the patches of your patchbomb. Then when all is
 done, patchbomb messages are displayed. If the PAGER environment
@@ -196,7 +196,7 b' def patchbomb(ui, repo, *revs, **opts):'
     description. Next, (optionally) if the diffstat program is
     installed and -d/--diffstat is used, the result of running
     diffstat on the patch. Finally, the patch itself, as generated by
-    "hg export".
+    :hg:`export`.
 
     By default the patch is included as text in the email body for
     easy reviewing. Using the -a/--attach option will instead create

hgext/purge.py

@@ -37,7 +37,7 b' def purge(ui, repo, *dirs, **opts):'
 
     This means that purge will delete:
 
-    - Unknown files: files marked with "?" by "hg status"
+    - Unknown files: files marked with "?" by :hg:`status`
     - Empty directories: in fact Mercurial ignores directories unless
       they contain files under source control management
 
@@ -45,7 +45,7 b' def purge(ui, repo, *dirs, **opts):'
 
     - Modified and unmodified tracked files
     - Ignored files (unless --all is specified)
-    - New files added to the repository (with "hg add")
+    - New files added to the repository (with :hg:`add`)
 
     If directories are given on the command line, only files in these
     directories are considered.

hgext/record.py

@@ -360,10 +360,10 b' def filterpatch(ui, chunks):'
 def record(ui, repo, *pats, **opts):
     '''interactively select changes to commit
 
-    If a list of files is omitted, all changes reported by "hg status"
+    If a list of files is omitted, all changes reported by :hg:`status`
     will be candidates for recording.
 
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    See :hg:`help dates` for a list of formats valid for -d/--date.
 
     You will be prompted for whether to record changes to each
     modified file, and for files with multiple changes, for each
@@ -388,7 +388,7 b' def record(ui, repo, *pats, **opts):'
 def qrecord(ui, repo, patch, *pats, **opts):
     '''interactively record a new patch
 
-    See 'hg help qnew' & 'hg help record' for more information and
+    See :hg:`help qnew` & :hg:`help record` for more information and
     usage.
     '''
 

mercurial/commands.py

@@ -32,7 +32,7 b' def add(ui, repo, *pats, **opts):'
     .. container:: verbose
 
        An example showing how new (unknown) files are added
-       automatically by ``hg add``::
+       automatically by :hg:`add`::
 
          $ ls
          foo.c
@@ -171,7 +171,7 b' def archive(ui, repo, dest, **opts):'
     :``zip``:   zip archive, compressed using deflate
 
     The exact name of the destination archive or directory is given
-    using a format string; see 'hg help export' for details.
+    using a format string; see :hg:`help export` for details.
 
     Each member added to an archive file has a directory prefix
     prepended. Use -p/--prefix to specify a format string for the
@@ -230,7 +230,7 b' def backout(ui, repo, node=None, rev=Non'
     changeset afterwards. This saves you from doing the merge by hand.
     The result of this merge is not committed, as with a normal merge.
 
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    See :hg:`help dates` for a list of formats valid for -d/--date.
     '''
     if rev and node:
         raise util.Abort(_("please specify just one revision"))
@@ -456,8 +456,8 b' def branch(ui, repo, label=None, **opts)'
     the parent of the working directory, negating a previous branch
     change.
 
-    Use the command 'hg update' to switch to an existing branch. Use
-    'hg commit --close-branch' to mark this branch as closed.
+    Use the command :hg:`update` to switch to an existing branch. Use
+    :hg:`commit --close-branch` to mark this branch as closed.
     """
 
     if opts.get('clean'):
@@ -485,7 +485,7 b' def branches(ui, repo, active=False, clo'
     If -a/--active is specified, only show active branches. A branch
     is considered active if it contains repository heads.
 
-    Use the command 'hg update' to switch to an existing branch.
+    Use the command :hg:`update` to switch to an existing branch.
     """
 
     hexfunc = ui.debugflag and hex or short
@@ -637,11 +637,11 b' def clone(ui, source, dest=None, **opts)'
     The location of the source is added to the new repository's
     .hg/hgrc file, as the default to be used for future pulls.
 
-    See 'hg help urls' for valid source format details.
+    See :hg:`help urls` for valid source format details.
 
     It is possible to specify an ``ssh://`` URL as the destination, but no
     .hg/hgrc and working directory will be created on the remote side.
-    Please see 'hg help urls' for important details about ``ssh://`` URLs.
+    Please see :hg:`help urls` for important details about ``ssh://`` URLs.
 
     A set of changesets (tags, or branch names) to pull may be specified
     by listing each changeset (tag, or branch name) with -r/--rev.
@@ -705,7 +705,7 b' def commit(ui, repo, *pats, **opts):'
     centralized RCS, this operation is a local operation. See hg push
     for a way to actively distribute your changes.
 
-    If a list of files is omitted, all changes reported by "hg status"
+    If a list of files is omitted, all changes reported by :hg:`status`
     will be committed.
 
     If you are committing the result of a merge, do not provide any
@@ -714,7 +714,7 b' def commit(ui, repo, *pats, **opts):'
     If no commit message is specified, the configured editor is
     started to prompt you for a message.
 
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    See :hg:`help dates` for a list of formats valid for -d/--date.
     """
     extra = {}
     if opts.get('close_branch'):
@@ -1151,7 +1151,7 b' def diff(ui, repo, *pats, **opts):'
     anyway, probably with undesirable results.
 
     Use the -g/--git option to generate diffs in the git extended diff
-    format. For more information, read 'hg help diffs'.
+    format. For more information, read :hg:`help diffs`.
     """
 
     revs = opts.get('rev')
@@ -1219,7 +1219,7 b' def export(ui, repo, *changesets, **opts'
     diff anyway, probably with undesirable results.
 
     Use the -g/--git option to generate diffs in the git extended diff
-    format. See 'hg help diffs' for more information.
+    format. See :hg:`help diffs` for more information.
 
     With the --switch-parent option, the diff will be against the
     second parent. It can be useful to review a merge.
@@ -1878,7 +1878,7 b' def import_(ui, repo, patch1, *patches, '
 
     To read a patch from standard input, use "-" as the patch name. If
     a URL is specified, the patch will be downloaded from it.
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    See :hg:`help dates` for a list of formats valid for -d/--date.
     """
     patches = (patch1,) + patches
 
@@ -2081,7 +2081,7 b' def init(ui, dest=".", **opts):'
     If no directory is given, the current directory is used.
 
     It is possible to specify an ``ssh://`` URL as the destination.
-    See 'hg help urls' for more information.
+    See :hg:`help urls` for more information.
     """
     hg.repository(cmdutil.remoteui(ui, opts), dest, create=1)
 
@@ -2136,7 +2136,7 b' def log(ui, repo, *pats, **opts):'
     --follow is set, in which case the working directory parent is
     used as the starting revision.
 
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    See :hg:`help dates` for a list of formats valid for -d/--date.
 
     By default this command prints revision number and changeset id,
     tags, non-trivial parents, user, date and time, and a summary for
@@ -2387,7 +2387,7 b' def paths(ui, repo, search=None):'
     unless a location is specified. When cloning a repository, the
     clone source is written as 'default' in .hg/hgrc.
 
-    See 'hg help urls' for more information.
+    See :hg:`help urls` for more information.
     """
     if search:
         for name, path in ui.configitems("paths"):
@@ -2429,7 +2429,7 b' def pull(ui, repo, source="default", **o'
     where X is the last changeset listed by hg incoming.
 
     If SOURCE is omitted, the 'default' path will be used.
-    See 'hg help urls' for more information.
+    See :hg:`help urls` for more information.
     """
     source, branches = hg.parseurl(ui.expandpath(source), opts.get('branch'))
     other = hg.repository(cmdutil.remoteui(repo, opts), source)
@@ -2465,7 +2465,7 b' def push(ui, repo, dest=None, **opts):'
     If -r/--rev is used, the named revision and all its ancestors will
     be pushed to the remote repository.
 
-    Please see 'hg help urls' for important details about ``ssh://``
+    Please see :hg:`help urls` for important details about ``ssh://``
     URLs. If DESTINATION is omitted, a default path will be used.
     """
     dest = ui.expandpath(dest or 'default-push', dest or 'default')
@@ -2663,8 +2663,8 b' def revert(ui, repo, *pats, **opts):'
 
     Using the -r/--rev option, revert the given files or directories
     to their contents as of a specific revision. This can be helpful
-    to "roll back" some or all of an earlier change. See 'hg help
-    dates' for a list of formats valid for -d/--date.
+    to "roll back" some or all of an earlier change. See :hg:`help
+    dates` for a list of formats valid for -d/--date.
 
     Revert modifies the working directory. It does not commit any
     changes, or change the parent of the working directory. If you
@@ -3213,7 +3213,7 b' def tag(ui, repo, name1, *names, **opts)'
     necessary. The file '.hg/localtags' is used for local tags (not
     shared among repositories).
 
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    See :hg:`help dates` for a list of formats valid for -d/--date.
     """
 
     rev_ = "."
@@ -3355,12 +3355,12 b' def update(ui, repo, node=None, rev=None'
     3. With the -C/--clean option, uncommitted changes are discarded and
        the working directory is updated to the requested changeset.
 
-    Use null as the changeset to remove the working directory (like 'hg
-    clone -U').
-
-    If you want to update just one file to an older changeset, use 'hg revert'.
-
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    Use null as the changeset to remove the working directory (like
+    :hg:`clone -U`).
+
+    If you want to update just one file to an older changeset, use :hg:`revert`.
+
+    See :hg:`help dates` for a list of formats valid for -d/--date.
     """
     if rev and node:
         raise util.Abort(_("please specify just one revision"))

mercurial/help/diffs.txt

@@ -16,7 +16,7 b' by default because a few widespread tool'
 format.
 
 This means that when generating diffs from a Mercurial repository
-(e.g. with "hg export"), you should be careful about things like file
+(e.g. with :hg:`export`), you should be careful about things like file
 copies and renames or other things mentioned above, because when
 applying a standard diff to a different repository, this extra
 information is lost. Mercurial's internal operations (like push and

mercurial/help/urls.txt

@@ -7,12 +7,12 b' Valid URLs are of the form::'
   ssh://[user[:pass]@]host[:port]/[path][#revision]
 
 Paths in the local filesystem can either point to Mercurial
-repositories or to bundle files (as created by 'hg bundle' or 'hg
-incoming --bundle').
+repositories or to bundle files (as created by :hg:`bundle` or :hg:`
+incoming --bundle`).
 
 An optional identifier after # indicates a particular branch, tag, or
-changeset to use from the remote repository. See also 'hg help
-revisions'.
+changeset to use from the remote repository. See also :hg:`help
+revisions`.
 
 Some features, such as pushing to http:// and https:// URLs are only
 possible if the feature is explicitly enabled on the remote Mercurial
@@ -47,7 +47,7 b' These URLs can all be stored in your hgr'
   ...
 
 You can then use the alias for any command that uses a URL (for
-example 'hg pull alias1' will be treated as 'hg pull URL1').
+example :hg:`pull alias1` will be treated as :hg:`pull URL1`).
 
 Two path aliases are special because they are used as defaults when
 you do not provide the URL to a command:

tests/test-help.out

@@ -391,7 +391,7 b' diff repository (or selected files)'
     with undesirable results.
 
     Use the -g/--git option to generate diffs in the git extended diff format.
-    For more information, read 'hg help diffs'.
+    For more information, read "hg help diffs".
 
 options:
 

tests/test-qrecord.out

@@ -28,7 +28,7 b' hg qrecord [OPTION]... PATCH [FILE]...'
 
 interactively record a new patch
 
-    See 'hg help qnew' & 'hg help record' for more information and usage.
+    See "hg help qnew" & "hg help record" for more information and usage.
 
 options:
 

tests/test-record.out

@@ -6,7 +6,7 b' interactively select changes to commit'
     If a list of files is omitted, all changes reported by "hg status" will be
     candidates for recording.
 
-    See 'hg help dates' for a list of formats valid for -d/--date.
+    See "hg help dates" for a list of formats valid for -d/--date.
 
     You will be prompted for whether to record changes to each modified file,
     and for files with multiple changes, for each change to use. For each