commands: use minirst parser when displaying help

hgext/convert/__init__.py

@@ -19,6 +19,7 b' def convert(ui, src, dest=None, revmapfi'
     """convert a foreign SCM repository to a Mercurial one.
 
     Accepted source formats [identifiers]:
+
     - Mercurial [hg]
     - CVS [cvs]
     - Darcs [darcs]
@@ -30,6 +31,7 b' def convert(ui, src, dest=None, revmapfi'
     - Perforce [p4]
 
     Accepted destination formats [identifiers]:
+
     - Mercurial [hg]
     - Subversion [svn] (history on branches is not preserved)
 
@@ -45,19 +47,21 b' def convert(ui, src, dest=None, revmapfi'
     uses --sourcesort to preserve original revision numbers order. Sort modes
     have the following effects:
 
-    --branchsort: convert from parent to child revision when possible, which
-      means branches are usually converted one after the other. It generates
-      more compact repositories.
-    --datesort: sort revisions by date. Converted repositories have
-      good-looking changelogs but are often an order of magnitude larger than
-      the same ones generated by --branchsort.
-    --sourcesort: try to preserve source revisions order, only supported by
+    --branchsort  convert from parent to child revision when possible, which
+                  means branches are usually converted one after the other. It
+                  generates more compact repositories.
+
+    --datesort    sort revisions by date. Converted repositories have
+                  good-looking changelogs but are often an order of magnitude
+                  larger than the same ones generated by --branchsort.
+
+    --sourcesort  try to preserve source revisions order, only supported by
       Mercurial sources.
 
     If <REVMAP> isn't given, it will be put in a default location
     (<dest>/.hg/shamap by default). The <REVMAP> is a simple text file that
     maps each source commit ID to the destination ID for that revision, like
-    so:
+    so::
 
     <source ID> <destination ID>
 
@@ -72,7 +76,7 b' def convert(ui, src, dest=None, revmapfi'
 
     The filemap is a file that allows filtering and remapping of files and
     directories. Comment lines start with '#'. Each line can contain one of
-    the following directives:
+    the following directives::
 
       include path/to/file
 
@@ -134,7 +138,7 b' def convert(ui, src, dest=None, revmapfi'
     Because CVS does not have changesets, it is necessary to collect
     individual commits to CVS and merge them into changesets. CVS source uses
     its internal changeset merging code by default but can be configured to
-    call the external 'cvsps' program by setting:
+    call the external 'cvsps' program by setting::
 
     --config convert.cvsps='cvsps -A -u --cvs-direct -q'
 
@@ -142,7 +146,7 b' def convert(ui, src, dest=None, revmapfi'
 
     The options shown are the defaults.
 
-    Internal cvsps is selected by setting
+    Internal cvsps is selected by setting ::
 
     --config convert.cvsps=builtin
 

hgext/keyword.py

@@ -38,7 +38,7 b' or for archive distribution.'
 Configuration is done in the [keyword] and [keywordmaps] sections of hgrc
 files.
 
-Example:
+Example::
 
     [keyword]
     # expand keywords in every python file except those matching "x*"

hgext/mq.py

@@ -14,7 +14,7 b' 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)::
 
 prepare repository to work with patches   qinit
 create new patch                          qnew

hgext/notify.py

@@ -10,7 +10,7 b''
 Subscriptions can be managed through a hgrc file. Default mode is to print
 messages to stdout, for testing and configuring.
 
-To use, configure the notify extension and enable it in hgrc like this:
+To use, configure the notify extension and enable it in hgrc like this::
 
   [extensions]
   hgext.notify =
@@ -24,11 +24,11 b' To use, configure the notify extension a'
   [notify]
   # config items go here
 
-Required configuration items:
+Required configuration items::
 
   config = /path/to/file # file containing subscriptions
 
-Optional configuration items:
+Optional configuration items::
 
   test = True            # print messages to stdout for testing
   strip = 3              # number of slashes to strip for url paths
@@ -50,6 +50,8 b' Optional configuration items:'
 The notify config file has same format as a regular hgrc file. It has two
 sections so you can express subscriptions in whatever way is handier for you.
 
+::
+
   [usersubs]
   # key is subscriber email, value is ","-separated list of glob patterns
   user@host = pattern

hgext/record.py

@@ -364,7 +364,7 b' def record(ui, repo, *pats, **opts):'
 
     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
-    query, the following responses are possible:
+    query, the following responses are possible::
 
     y - record this change
     n - skip this change

mercurial/commands.py

@@ -14,6 +14,7 b' import patch, help, mdiff, url, encoding'
 import archival, changegroup, cmdutil, sshserver, hbisect
 from hgweb import server
 import merge as merge_
+import minirst
 
 # Commands start here, listed alphabetically
 
@@ -133,7 +134,7 b' def archive(ui, repo, dest, **opts):'
     By default, the revision used is the parent of the working directory; use
     -r/--rev to specify a different revision.
 
-    To specify the type of archive to create, use -t/--type. Valid types are:
+    To specify the type of archive to create, use -t/--type. Valid types are::
 
     "files" (default): a directory full of files
     "tar": tar archive, uncompressed
@@ -550,7 +551,7 b' def cat(ui, repo, file1, *pats, **opts):'
 
     Output may be to a file, in which case the name of the file is given using
     a format string. The formatting rules are the same as for the export
-    command, with the following additions:
+    command, with the following additions::
 
     %s   basename of file being printed
     %d   dirname of file being printed, or '.' if in repository root
@@ -600,7 +601,7 b' def clone(ui, source, dest=None, **opts)'
     cases, use the --pull option to avoid hardlinking.
 
     In some cases, you can clone repositories and checked out files using full
-    hardlinks with
+    hardlinks with ::
 
       $ cp -al REPO REPOCLONE
 
@@ -1095,7 +1096,7 b' def export(ui, repo, *changesets, **opts'
     it will compare the merge changeset against its first parent only.
 
     Output may be to a file, in which case the name of the file is given using
-    a format string. The formatting rules are as follows:
+    a format string. The formatting rules are as follows::
 
     %%   literal "%" character
     %H   changeset hash (40 bytes of hexadecimal)
@@ -1397,6 +1398,7 b' def help_(ui, name=None, with_version=Fa'
     Given a topic, extension, or command name, print help for that topic.
     """
     option_lists = []
+    textwidth = util.termwidth() - 2
 
     def addglobalopts(aliases):
         if ui.verbose:
@@ -1449,7 +1451,7 b' def help_(ui, name=None, with_version=Fa'
             doc = _("(no help text available)")
         if ui.quiet:
             doc = doc.splitlines()[0]
-        ui.write("\n%s\n" % doc.rstrip())
+        ui.write("\n%s\n" % minirst.format(doc, textwidth))
 
         if not ui.quiet:
             # options
@@ -1498,7 +1500,9 b' def help_(ui, name=None, with_version=Fa'
 
         if name != 'shortlist':
             exts, maxlength = extensions.enabled()
-            ui.write(help.listexts(_('enabled extensions:'), exts, maxlength))
+            text = help.listexts(_('enabled extensions:'), exts, maxlength)
+            if text:
+                ui.write("\n%s\n" % minirst.format(text, textwidth))
 
         if not ui.quiet:
             addglobalopts(True)
@@ -1516,8 +1520,8 b' def help_(ui, name=None, with_version=Fa'
         if hasattr(doc, '__call__'):
             doc = doc()
 
-        ui.write("%s\n" % header)
-        ui.write("%s\n" % doc.rstrip())
+        ui.write("%s\n\n" % header)
+        ui.write("%s\n" % minirst.format(doc, textwidth))
 
     def helpext(name):
         try:
@@ -1526,12 +1530,11 b' def help_(ui, name=None, with_version=Fa'
             raise error.UnknownCommand(name)
 
         doc = gettext(mod.__doc__) or _('no help text available')
-        doc = doc.splitlines()
-        ui.write(_('%s extension - %s\n') % (name.split('.')[-1], doc[0]))
-        for d in doc[1:]:
-            ui.write(d, '\n')
-
-        ui.status('\n')
+        head, tail = doc.split('\n', 1)
+        ui.write(_('%s extension - %s\n\n') % (name.split('.')[-1], head))
+        if tail:
+            ui.write(minirst.format(tail, textwidth))
+            ui.status('\n\n')
 
         try:
             ct = mod.cmdtable
@@ -2329,7 +2332,7 b' def remove(ui, repo, *pats, **opts):'
     The following table details the behavior of remove for different file
     states (columns) and option combinations (rows). The file states are Added
     [A], Clean [C], Modified [M] and Missing [!] (as reported by hg status).
-    The actions are Warn, Remove (from branch) and Delete (from disk).
+    The actions are Warn, Remove (from branch) and Delete (from disk)::
 
            A  C  M  !
     none   W  RD W  R
@@ -2410,7 +2413,8 b' def resolve(ui, repo, *pats, **opts):'
     whether or not files are resolved. All files must be marked as resolved
     before a commit is permitted.
 
-    The codes used to show the status of files are:
+    The codes used to show the status of files are::
+
     U = unresolved
     R = resolved
     """
@@ -2675,7 +2679,7 b' def rollback(ui, repo):'
     Transactions are used to encapsulate the effects of all commands that
     create new changesets or propagate existing changesets into a repository.
     For example, the following commands are transactional, and their effects
-    can be rolled back:
+    can be rolled back::
 
       commit
       import
@@ -2783,7 +2787,8 b' def status(ui, repo, *pats, **opts):'
     If one revision is given, it is used as the base revision. If two
     revisions are given, the differences between them are shown.
 
-    The codes used to show the status of files are:
+    The codes used to show the status of files are::
+
     M = modified
     A = added
     R = removed

mercurial/help.py

@@ -43,9 +43,10 b' def listexts(header, exts, maxlength):'
     '''return a text listing of the given extensions'''
     if not exts:
         return ''
-    result = '\n%s\n\n' % header
+    # TODO: literal block is wrong, should be a field list or a simple table.
+    result = '\n%s\n\n ::\n\n' % header
     for name, desc in sorted(exts.iteritems()):
-        desc = util.wrap(desc, maxlength + 4)
+        desc = util.wrap(desc, maxlength + 5)
         result += ' %s   %s\n' % (name.ljust(maxlength), desc)
     return result
 
@@ -63,18 +64,18 b' def extshelp():'
     to activate extensions as needed.
 
     To enable the "foo" extension, either shipped with Mercurial or in the
-    Python search path, create an entry for it in your hgrc, like this:
+    Python search path, create an entry for it in your hgrc, like this::
 
       [extensions]
       foo =
 
-    You may also specify the full path to an extension:
+    You may also specify the full path to an extension::
 
       [extensions]
       myfeature = ~/.hgext/myfeature.py
 
     To explicitly disable an extension enabled in an hgrc of broader scope,
-    prepend its path with !:
+    prepend its path with !::
 
       [extensions]
       # disabling extension bar residing in /path/to/extension/bar.py
@@ -95,10 +96,11 b' helptable = ('
     (["dates"], _("Date Formats"),
      _(r'''
     Some commands allow the user to specify a date, e.g.:
-    * backout, commit, import, tag: Specify the commit date.
-    * log, revert, update: Select revision(s) by date.
 
-    Many date formats are valid. Here are some examples:
+    - backout, commit, import, tag: Specify the commit date.
+    - log, revert, update: Select revision(s) by date.
+
+    Many date formats are valid. Here are some examples::
 
     "Wed Dec 6 13:18:29 2006" (local timezone assumed)
     "Dec 6 13:18 -0600" (year assumed, time offset provided)
@@ -123,7 +125,7 b' helptable = ('
     offset of the local timezone, in seconds west of UTC (negative if the
     timezone is east of UTC).
 
-    The log command also accepts date ranges:
+    The log command also accepts date ranges::
 
     "<{datetime}" - at or before a given date/time
     ">{datetime}" - on or after a given date/time
@@ -155,23 +157,23 b' helptable = ('
     To use a Perl/Python regular expression, start a name with "re:". Regexp
     pattern matching is anchored at the root of the repository.
 
-    Plain examples:
+    Plain examples::
 
     path:foo/bar   a name bar in a directory named foo in the root of
                    the repository
     path:path:name a file or directory named "path:name"
 
-    Glob examples:
+    Glob examples::
 
     glob:*.c       any name ending in ".c" in the current directory
     *.c            any name ending in ".c" in the current directory
-    **.c           any name ending in ".c" in any subdirectory of the current
-                   directory including itself.
+      **.c           any name ending in ".c" in any subdirectory of the
+                     current directory including itself.
     foo/*.c        any name ending in ".c" in the directory foo
     foo/**.c       any name ending in ".c" in any subdirectory of foo
                    including itself.
 
-    Regexp examples:
+    Regexp examples::
 
     re:.*\.c$      any name ending in ".c", anywhere in the repository
 
@@ -179,76 +181,77 b' helptable = ('
 
     (['environment', 'env'], _('Environment Variables'),
      _(r'''
-HG::
+HG
     Path to the 'hg' executable, automatically passed when running hooks,
     extensions or external tools. If unset or empty, this is the hg
     executable's name if it's frozen, or an executable named 'hg' (with
     %PATHEXT% [defaulting to COM/EXE/BAT/CMD] extensions on Windows) is
     searched.
 
-HGEDITOR::
+HGEDITOR
     This is the name of the editor to run when committing. See EDITOR.
 
     (deprecated, use .hgrc)
 
-HGENCODING::
+HGENCODING
     This overrides the default locale setting detected by Mercurial. This
     setting is used to convert data including usernames, changeset
     descriptions, tag names, and branches. This setting can be overridden with
     the --encoding command-line option.
 
-HGENCODINGMODE::
+HGENCODINGMODE
     This sets Mercurial's behavior for handling unknown characters while
     transcoding user input. The default is "strict", which causes Mercurial to
     abort if it can't map a character. Other settings include "replace", which
     replaces unknown characters, and "ignore", which drops them. This setting
     can be overridden with the --encodingmode command-line option.
 
-HGMERGE::
+HGMERGE
     An executable to use for resolving merge conflicts. The program will be
     executed with three arguments: local file, remote file, ancestor file.
 
     (deprecated, use .hgrc)
 
-HGRCPATH::
+HGRCPATH
     A list of files or directories to search for hgrc files. Item separator is
     ":" on Unix, ";" on Windows. If HGRCPATH is not set, platform default
     search path is used. If empty, only the .hg/hgrc from the current
     repository is read.
 
     For each element in HGRCPATH:
-    * if it's a directory, all files ending with .rc are added
-    * otherwise, the file itself will be added
 
-HGUSER::
+    - if it's a directory, all files ending with .rc are added
+    - otherwise, the file itself will be added
+
+HGUSER
     This is the string used as the author of a commit. If not set, available
     values will be considered in this order:
 
-    * HGUSER (deprecated)
-    * hgrc files from the HGRCPATH
-    * EMAIL
-    * interactive prompt
-    * LOGNAME (with '@hostname' appended)
+    - HGUSER (deprecated)
+    - hgrc files from the HGRCPATH
+    - EMAIL
+    - interactive prompt
+    - LOGNAME (with '@hostname' appended)
 
     (deprecated, use .hgrc)
 
-EMAIL::
+EMAIL
     May be used as the author of a commit; see HGUSER.
 
-LOGNAME::
+LOGNAME
     May be used as the author of a commit; see HGUSER.
 
-VISUAL::
+VISUAL
     This is the name of the editor to use when committing. See EDITOR.
 
-EDITOR::
+EDITOR
     Sometimes Mercurial needs to open a text file in an editor for a user to
     modify, for example when writing commit messages. The editor it uses is
     determined by looking at the environment variables HGEDITOR, VISUAL and
     EDITOR, in that order. The first non-empty one is chosen. If all of them
     are empty, the editor defaults to 'vi'.
 
-PYTHONPATH::
+PYTHONPATH
     This is used by Python to find imported modules and may need to be set
     appropriately if this Mercurial is not installed system-wide.
     ''')),
@@ -431,7 +434,7 b' PYTHONPATH::'
 
     (['urls'], _('URL Paths'),
      _(r'''
-    Valid URLs are of the form:
+    Valid URLs are of the form::
 
       local/filesystem/path[#revision]
       file://local/filesystem/path[#revision]
@@ -450,22 +453,28 b' PYTHONPATH::'
     server.
 
     Some notes about using SSH with Mercurial:
+
     - SSH requires an accessible shell account on the destination machine and
       a copy of hg in the remote path or specified with as remotecmd.
     - path is relative to the remote user's home directory by default. Use an
-      extra slash at the start of a path to specify an absolute path:
+      extra slash at the start of a path to specify an absolute path::
+
         ssh://example.com//tmp/repository
+
     - Mercurial doesn't use its own compression via SSH; the right thing to do
-      is to configure it in your ~/.ssh/config, e.g.:
+      is to configure it in your ~/.ssh/config, e.g.::
+
         Host *.mylocalnetwork.example.com
           Compression no
         Host *
           Compression yes
+
       Alternatively specify "ssh -C" as your ssh command in your hgrc or with
       the --ssh command line option.
 
     These URLs can all be stored in your hgrc with path aliases under the
-    [paths] section like so:
+    [paths] section like so::
+
     [paths]
     alias1 = URL1
     alias2 = URL2

tests/test-convert.out

@@ -3,6 +3,7 b' hg convert [OPTION]... SOURCE [DEST [REV'
 convert a foreign SCM repository to a Mercurial one.
 
     Accepted source formats [identifiers]:
+
     - Mercurial [hg]
     - CVS [cvs]
     - Darcs [darcs]
@@ -14,6 +15,7 b' convert a foreign SCM repository to a Me'
     - Perforce [p4]
 
     Accepted destination formats [identifiers]:
+
     - Mercurial [hg]
     - Subversion [svn] (history on branches is not preserved)
 
@@ -29,13 +31,13 b' convert a foreign SCM repository to a Me'
     uses --sourcesort to preserve original revision numbers order. Sort modes
     have the following effects:
 
-    --branchsort: convert from parent to child revision when possible, which
-      means branches are usually converted one after the other. It generates
-      more compact repositories.
-    --datesort: sort revisions by date. Converted repositories have
-      good-looking changelogs but are often an order of magnitude larger than
-      the same ones generated by --branchsort.
-    --sourcesort: try to preserve source revisions order, only supported by
+    --branchsort  convert from parent to child revision when possible, which
+                  means branches are usually converted one after the other. It
+                  generates more compact repositories.
+    --datesort    sort revisions by date. Converted repositories have good-
+                  looking changelogs but are often an order of magnitude
+                  larger than the same ones generated by --branchsort.
+    --sourcesort  try to preserve source revisions order, only supported by
       Mercurial sources.
 
     If <REVMAP> isn't given, it will be put in a default location

tests/test-help.out

@@ -267,6 +267,7 b' show changed files in the working direct'
     revisions are given, the differences between them are shown.
 
     The codes used to show the status of files are:
+
     M = modified
     A = added
     R = removed