Merge "update markdown/help header format"
diff --git a/docs/ b/docs/
index cf48698..c85726b 100644
--- a/docs/
+++ b/docs/
@@ -1,5 +1,4 @@
-repo Manifest Format
+# repo Manifest Format
 A repo manifest describes the structure of a repo client; that is
 the directories that are visible and where they should be obtained
@@ -15,8 +14,7 @@
-XML File Format
+## XML File Format
 A manifest XML file (e.g. `default.xml`) roughly conforms to the
 following DTD:
@@ -107,14 +105,12 @@
 A description of the elements and their attributes follows.
-Element manifest
+### Element manifest
 The root element of the file.
-Element remote
+### Element remote
 One or more remote elements may be specified.  Each remote element
 specifies a Git URL shared by one or more projects and (optionally)
@@ -149,8 +145,7 @@
 `refs/heads/master`). Remotes with their own revision will override
 the default revision.
-Element default
+### Element default
 At most one default element may be specified.  Its remote and
 revision attributes are used when a project element does not
@@ -188,8 +183,7 @@
 the other ref tags.
-Element manifest-server
+### Element manifest-server
 At most one manifest-server may be specified. The url attribute
 is used to specify the URL of a manifest server, which is an
@@ -217,8 +211,7 @@
 is given.
-Element project
+### Element project
 One or more project elements may be specified.  Each element
 describes a single Git repository to be cloned into the repo
@@ -295,8 +288,7 @@
 local mirrors syncing, it will be ignored when syncing the projects in a
 client working directory.
-Element extend-project
+### Element extend-project
 Modify the attributes of the named project.
@@ -314,8 +306,7 @@
 Attribute `revision`: If specified, overrides the revision of the original
 project.  Same syntax as the corresponding element of `project`.
-Element annotation
+### Element annotation
 Zero or more annotation elements may be specified as children of a
 project element. Each element describes a name-value pair that will be
@@ -325,8 +316,7 @@
 "false".  This attribute determines whether or not the annotation will
 be kept when exported with the manifest subcommand.
-Element copyfile
+### Element copyfile
 Zero or more copyfile elements may be specified as children of a
 project element. Each element describes a src-dest pair of files;
@@ -334,14 +324,12 @@
 "src" is project relative, "dest" is relative to the top of the tree.
-Element linkfile
+### Element linkfile
 It's just like copyfile and runs at the same time as copyfile but
 instead of copying it creates a symlink.
-Element remove-project
+### Element remove-project
 Deletes the named project from the internal manifest table, possibly
 allowing a subsequent project element in the same manifest file to
@@ -351,8 +339,7 @@
 the user can remove a project, and possibly replace it with their
 own definition.
-Element include
+### Element include
 This element provides the capability of including another manifest
 file into the originating manifest.  Normal rules apply for the
@@ -362,8 +349,7 @@
 the manifest repository's root.
-Local Manifests
+## Local Manifests
 Additional remotes and projects may be added through local manifest
 files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
diff --git a/subcmds/ b/subcmds/
index 2902684..fa1dff6 100644
--- a/subcmds/
+++ b/subcmds/
@@ -67,8 +67,7 @@
 Summarizes the currently available topic branches.
-Branch Display
+# Branch Display
 The branch display output by this command is organized into four
 columns of information; for example:
diff --git a/subcmds/ b/subcmds/
index 693949e..6fb16f1 100644
--- a/subcmds/
+++ b/subcmds/
@@ -53,8 +53,7 @@
 The -r option allows running the command only on projects matching
 regex or wildcard expression.
-Output Formatting
+# Output Formatting
 The -p option causes '%prog' to bind pipes to the command's stdin,
 stdout and stderr streams, and pipe all output into a continuous
@@ -71,8 +70,7 @@
 causes command output to be suppressed until the command produces
 at least one byte of output on stdout.
+# Environment
 pwd is the project's working directory.  If the current client is
 a mirror client, then pwd is the Git repository.
diff --git a/subcmds/ b/subcmds/
index dd391cf..1157355 100644
--- a/subcmds/
+++ b/subcmds/
@@ -33,8 +33,7 @@
   helpDescription = """
 Search for the specified patterns in all project files.
-Boolean Options
+# Boolean Options
 The following options can appear as often as necessary to express
 the pattern to locate:
@@ -47,8 +46,7 @@
 than one tree, only the first result is reported, prefixed by the
 revision name it was found under.
+# Examples
 Look for a line that has '#define' and either 'MAX_PATH or 'PATH_MAX':
diff --git a/subcmds/ b/subcmds/
index 9bb4c8c..67a225e 100644
--- a/subcmds/
+++ b/subcmds/
@@ -107,15 +107,13 @@
         self.heading('%s', heading)
-        self.heading('%s', ''.ljust(len(heading), '-'))
         me = 'repo %s' % cmd.NAME
         body = body.strip()
         body = body.replace('%prog', me)
-        asciidoc_hdr = re.compile(r'^\n?([^\n]{1,})\n([=~-]{2,})$')
+        asciidoc_hdr = re.compile(r'^\n?#+ (.+)$')
         for para in body.split("\n\n"):
           if para.startswith(' '):
             self.write('%s', para)
@@ -125,19 +123,8 @@
           m = asciidoc_hdr.match(para)
           if m:
-            title =
-            section_type =
-            if section_type[0] in ('=', '-'):
-              p = self.heading
-            else:
-              def _p(fmt, *args):
-                self.write('  ')
-                self.heading(fmt, *args)
-              p = _p
-            p('%s', title)
+            self.heading(
-            p('%s', ''.ljust(len(title), section_type[0]))
diff --git a/subcmds/ b/subcmds/
index 47a1c9f..4e51dfe 100644
--- a/subcmds/
+++ b/subcmds/
@@ -67,8 +67,7 @@
 may be necessary if there are problems with the local Python
 HTTP client or proxy configuration, but the Git binary works.
-Switching Manifest Branches
+# Switching Manifest Branches
 To switch to another manifest branch, `repo init -b otherbranch`
 may be used in an existing client.  However, as this only updates the
diff --git a/subcmds/ b/subcmds/
index 60e26ff..b47c873 100644
--- a/subcmds/
+++ b/subcmds/
@@ -49,8 +49,7 @@
 dir/subdir/proj2 are repo projects, dir/subdir/proj3 will be shown
 if it is not known to repo.
-Status Display
+# Status Display
 The status display is organized into three columns of information,
 for example if the file 'subcmds/' is modified in the
diff --git a/subcmds/ b/subcmds/
index cda47fd..943a026 100644
--- a/subcmds/
+++ b/subcmds/
@@ -155,8 +155,7 @@
 The --prune option can be used to remove any refs that no longer
 exist on the remote.
-SSH Connections
+# SSH Connections
 If at least one project remote URL uses an SSH connection (ssh://,
 git+ssh://, or user@host:path syntax) repo will automatically
@@ -170,8 +169,7 @@
   export GIT_SSH=ssh
+# Compatibility
 This feature is automatically disabled on Windows, due to the lack
 of UNIX domain socket support.
diff --git a/subcmds/ b/subcmds/
index d12efd1..02b43b4 100644
--- a/subcmds/
+++ b/subcmds/
@@ -78,8 +78,7 @@
 new users.  Users passed as --reviewers must already be registered
 with the code review system, or the upload will fail.
+# Configuration
@@ -126,8 +125,7 @@
 of the -t option to the repo command. If unset or set to "false" then
 repo will make use of only the command line option.
+# References
 Gerrit Code Review: