Add a 'repo manifest' command whose help is the manifest file format

This should make it easier for users to discover the file format
on their own, and read about it.

Signed-off-by: Shawn O. Pearce <sop@google.com>

docs/manifest-format.txt

@@ -19,39 +19,39 @@ XML File Format
 A manifest XML file (e.g. 'default.xml') roughly conforms to the
 following DTD:
 
-<!DOCTYPE manifest [
-  <!ELEMENT manifest (remote*,
-                      default?,
-                      remove-project*,
-                      project*,
-                      add-remote*)>
-
-  <!ELEMENT remote (EMPTY)>
-  <!ATTLIST remote name         ID    #REQUIRED>
-  <!ATTLIST remote fetch        CDATA #REQUIRED>
-  <!ATTLIST remote review       CDATA #IMPLIED>
-  <!ATTLIST remote project-name CDATA #IMPLIED>
-
-  <!ELEMENT default (EMPTY)>
-  <!ATTLIST default remote   IDREF #IMPLIED>
-  <!ATTLIST default revision CDATA #IMPLIED>
-
-  <!ELEMENT project (remote*)>
-  <!ATTLIST project name     CDATA #REQUIRED>
-  <!ATTLIST project path     CDATA #IMPLIED>
-  <!ATTLIST project remote   IDREF #IMPLIED>
-  <!ATTLIST project revision CDATA #IMPLIED>
-
-  <!ELEMENT add-remote (EMPTY)>
-  <!ATTLIST add-remote to-project   ID    #REQUIRED>
-  <!ATTLIST add-remote name         ID    #REQUIRED>
-  <!ATTLIST add-remote fetch        CDATA #REQUIRED>
-  <!ATTLIST add-remote review       CDATA #IMPLIED>
-  <!ATTLIST add-remote project-name CDATA #IMPLIED>
-
-  <!ELEMENT remove-project (EMPTY)>
-  <!ATTLIST remove-project name  CDATA #REQUIRED>
-]>
+  <!DOCTYPE manifest [
+    <!ELEMENT manifest (remote*,
+                        default?,
+                        remove-project*,
+                        project*,
+                        add-remote*)>
+  
+    <!ELEMENT remote (EMPTY)>
+    <!ATTLIST remote name         ID    #REQUIRED>
+    <!ATTLIST remote fetch        CDATA #REQUIRED>
+    <!ATTLIST remote review       CDATA #IMPLIED>
+    <!ATTLIST remote project-name CDATA #IMPLIED>
+  
+    <!ELEMENT default (EMPTY)>
+    <!ATTLIST default remote   IDREF #IMPLIED>
+    <!ATTLIST default revision CDATA #IMPLIED>
+  
+    <!ELEMENT project (remote*)>
+    <!ATTLIST project name     CDATA #REQUIRED>
+    <!ATTLIST project path     CDATA #IMPLIED>
+    <!ATTLIST project remote   IDREF #IMPLIED>
+    <!ATTLIST project revision CDATA #IMPLIED>
+  
+    <!ELEMENT add-remote (EMPTY)>
+    <!ATTLIST add-remote to-project   ID    #REQUIRED>
+    <!ATTLIST add-remote name         ID    #REQUIRED>
+    <!ATTLIST add-remote fetch        CDATA #REQUIRED>
+    <!ATTLIST add-remote review       CDATA #IMPLIED>
+    <!ATTLIST add-remote project-name CDATA #IMPLIED>
+  
+    <!ELEMENT remove-project (EMPTY)>
+    <!ATTLIST remove-project name  CDATA #REQUIRED>
+  ]>
 
 A description of the elements and their attributes follows.
 
@@ -179,16 +179,14 @@ manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`.
 
 For example:
 
-----
-	$ cat .repo/local_manifest.xml
-	<?xml version="1.0" encoding="UTF-8"?>
-	<manifest>
-	  <project path="manifest"
-			   name="tools/manifest" />
-	  <project path="platform-manifest"
-			   name="platform/manifest" />
-	</manifest>
-----
+  $ cat .repo/local_manifest.xml
+  <?xml version="1.0" encoding="UTF-8"?>
+  <manifest>
+    <project path="manifest"
+             name="tools/manifest" />
+    <project path="platform-manifest"
+             name="platform/manifest" />
+  </manifest>
 
 Users may add projects to the local manifest prior to a `repo sync`
 invocation, instructing repo to automatically download and manage

subcmds/help.py

@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import re
 import sys
 from formatter import AbstractFormatter, DumbWriter
 
@@ -106,14 +107,24 @@ See 'repo help --all' for a complete list of recognized commands.
         body = body.strip()
         body = body.replace('%prog', me)
 
+        asciidoc_hdr = re.compile(r'^\n?([^\n]{1,})\n(={2,}|-{2,})$')
         for para in body.split("\n\n"):
           if para.startswith(' '):
             self.write('%s', para)
             self.nl()
             self.nl()
-          else:
-            self.wrap.add_flowing_data(para)
-            self.wrap.end_paragraph(1)
+            continue
+
+          m = asciidoc_hdr.match(para)
+          if m:
+            self.heading('%s', m.group(1))
+            self.nl()
+            self.heading('%s', ''.ljust(len(m.group(1)),'-'))
+            self.nl()
+            continue
+
+          self.wrap.add_flowing_data(para)
+          self.wrap.end_paragraph(1)
         self.wrap.end_paragraph(0)
 
     out = _Out(self.manifest.globalConfig)

subcmds/manifest.py

@@ -0,0 +1,44 @@
+#
+# Copyright (C) 2009 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+
+from command import Command
+
+class Manifest(Command):
+  common = False
+  helpSummary = "Manifest file"
+  helpUsage = """
+%prog
+"""
+  _helpDescription = """
+The repo manifest file describes the projects mapped into the client.
+"""
+
+  @property
+  def helpDescription(self):
+    help = self._helpDescription + '\n'
+    r = os.path.dirname(__file__)
+    r = os.path.dirname(r)
+    fd = open(os.path.join(r, 'docs', 'manifest-format.txt'))
+    for line in fd:
+      help += line
+    fd.close()
+    return help
+
+  def Execute(self, opt, args):
+    print >>sys.stderr, 'error: see repo help manifest'
+    sys.exit(1)