From b8f7bb04d003f8dbcf3ef2b201fc2678308995af Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Wed, 10 Oct 2018 01:05:11 -0400 Subject: [PATCH] update markdown/help header format Since gitiles recommends using # headers over ---/=== underlines, change the manifest-format.md over and all our help texts. Change-Id: I96391d41fba769e9f26870d497cf7cf01c8d8ab3 --- docs/manifest-format.md | 42 ++++++++++++++--------------------------- subcmds/branches.py | 3 +-- subcmds/forall.py | 6 ++---- subcmds/grep.py | 6 ++---- subcmds/help.py | 17 ++--------------- subcmds/init.py | 3 +-- subcmds/status.py | 3 +-- subcmds/sync.py | 6 ++---- subcmds/upload.py | 6 ++---- 9 files changed, 27 insertions(+), 65 deletions(-) diff --git a/docs/manifest-format.md b/docs/manifest-format.md index cf48698d..c85726bc 100644 --- a/docs/manifest-format.md +++ b/docs/manifest-format.md @@ -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 @@ obtained by clients during `repo sync`. [TOC] -XML File Format ---------------- +## XML File Format A manifest XML file (e.g. `default.xml`) roughly conforms to the following DTD: @@ -107,14 +105,12 @@ following DTD: 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 @@ Attribute `revision`: Name of a Git branch (e.g. `master` or `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 @@ branch (specified in the `revision` attribute) rather than 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 @@ the specified tag. This is used by repo sync when the --smart-tag option 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 @@ rather than the `name` attribute. This attribute only applies to the 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 @@ belongs. Same syntax as the corresponding element of `project`. 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 @@ prefixed with REPO__. In addition, there is an optional attribute "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 @@ the "src" file will be copied to the "dest" place during `repo sync` command. "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 @@ This element is mostly useful in a local manifest file, where 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 @@ Attribute `name`: the manifest to include, specified relative to 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/branches.py b/subcmds/branches.py index 2902684a..fa1dff67 100644 --- a/subcmds/branches.py +++ b/subcmds/branches.py @@ -67,8 +67,7 @@ class Branches(Command): 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/forall.py b/subcmds/forall.py index 693949e2..6fb16f16 100644 --- a/subcmds/forall.py +++ b/subcmds/forall.py @@ -53,8 +53,7 @@ Executes the same shell command in each project. 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 @@ command produces output only on stderr. Normally the -p option causes command output to be suppressed until the command produces at least one byte of output on stdout. -Environment ------------ +# 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/grep.py b/subcmds/grep.py index dd391cfa..1157355d 100644 --- a/subcmds/grep.py +++ b/subcmds/grep.py @@ -33,8 +33,7 @@ class Grep(PagedCommand): 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 @@ in order to scan multiple trees. If the same file matches in more than one tree, only the first result is reported, prefixed by the revision name it was found under. -Examples -------- +# Examples Look for a line that has '#define' and either 'MAX_PATH or 'PATH_MAX': diff --git a/subcmds/help.py b/subcmds/help.py index 9bb4c8c7..67a225e5 100644 --- a/subcmds/help.py +++ b/subcmds/help.py @@ -107,15 +107,13 @@ Displays detailed usage information about a command. self.heading('%s', heading) self.nl() - - self.heading('%s', ''.ljust(len(heading), '-')) self.nl() 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 @@ Displays detailed usage information about a command. m = asciidoc_hdr.match(para) if m: - title = m.group(1) - section_type = m.group(2) - 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(m.group(1)) self.nl() - p('%s', ''.ljust(len(title), section_type[0])) self.nl() continue diff --git a/subcmds/init.py b/subcmds/init.py index 47a1c9fa..4e51dfe8 100644 --- a/subcmds/init.py +++ b/subcmds/init.py @@ -67,8 +67,7 @@ resumeable bundle file on a content delivery network. This 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/status.py b/subcmds/status.py index 60e26ff4..b47c8736 100644 --- a/subcmds/status.py +++ b/subcmds/status.py @@ -49,8 +49,7 @@ includes deeper items. For example, if dir/subdir/proj1 and 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/status.py' is modified in the diff --git a/subcmds/sync.py b/subcmds/sync.py index cda47fdd..943a0264 100644 --- a/subcmds/sync.py +++ b/subcmds/sync.py @@ -155,8 +155,7 @@ exist locally. 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 @@ environment variable to 'ssh'. For example: export GIT_SSH=ssh %prog -Compatibility -~~~~~~~~~~~~~ +# Compatibility This feature is automatically disabled on Windows, due to the lack of UNIX domain socket support. diff --git a/subcmds/upload.py b/subcmds/upload.py index fdc7e28d..c1f5c0ff 100644 --- a/subcmds/upload.py +++ b/subcmds/upload.py @@ -78,8 +78,7 @@ added to the respective list of users, and emails are sent to any new users. Users passed as --reviewers must already be registered with the code review system, or the upload will fail. -Configuration -------------- +# Configuration review.URL.autoupload: @@ -126,8 +125,7 @@ is set to "true" then repo will assume you always want the equivalent 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 ----------- +# References Gerrit Code Review: http://code.google.com/p/gerrit/