Fix broken synopsis formatting in documentation

Most of the cmd-xxxx.txt pages were still using the legacy 'italics' asciidoc [1], which caused the synopsis sections to render like this: 'ssh' -p <port> 'gerrit some-command' Furthermore, the line breaks and indentations were not rendered. Replaced the legacy 'italics" with _italics_ in all synopsis sections and changed the block type to [verse]. Verse blocks preserve indents and line breaks (like <pre> in HTML), but still allow text formatting. Fixed also some other minor mistakes and formatting errors. [1] http://asciidoctor.org/docs/migration/#migration-cheatsheet Change-Id: I457c5e42e3758789f29541d38d6f6c2e25532897 Signed-off-by: Michael Ochmann <michael.ochmann@sap.com>
2016-06-23 17:07:37 +02:00 · 2016-06-23 17:07:37 +02:00 · e2d76a1c23
commit e2d76a1c23
parent 9ea8b684b7
44 changed files with 109 additions and 61 deletions
--- a/Documentation/cmd-apropos.txt
+++ b/Documentation/cmd-apropos.txt
@ -4,8 +4,9 @@
 gerrit apropos - Search Gerrit documentation index

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit apropos'
+_ssh_ -p <port> <host> _gerrit apropos_
  <query>
 --

@ -23,8 +24,9 @@ Note: this feature is only available if documentation index was built.

 == EXAMPLES

-=====
+----
 $ ssh -p 29418 review.example.com gerrit apropos capabilities
+
    Gerrit Code Review - /config/ REST API:
    http://localhost:8080/Documentation/rest-api-config.html

@ -45,7 +47,7 @@ $ ssh -p 29418 review.example.com gerrit apropos capabilities

    Gerrit Code Review - /access/ REST API:
    http://localhost:8080/Documentation/rest-api-access.html
-=====
+----

 == SEE ALSO

--- a/Documentation/cmd-ban-commit.txt
+++ b/Documentation/cmd-ban-commit.txt
@ -4,8 +4,9 @@
 gerrit ban-commit - Bans a commit from a project's repository.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ban-commit'
+_ssh_ -p <port> <host> _gerrit ban-commit_
  [--reason <REASON>]
  <PROJECT>
  <COMMIT> ...
--- a/Documentation/cmd-cherry-pick.txt
+++ b/Documentation/cmd-cherry-pick.txt
@ -4,10 +4,11 @@
 gerrit-cherry-pick - Download and cherry pick one or more changes

 == SYNOPSIS
+[verse]
 --
-'gerrit-cherry-pick' <remote> <changeid>...
-'gerrit-cherry-pick' --continue | --skip | --abort
-'gerrit-cherry-pick' --close <remote>
+_gerrit-cherry-pick_ <remote> <changeid>...
+_gerrit-cherry-pick_ --continue | --skip | --abort
+_gerrit-cherry-pick_ --close <remote>
 --

 == DESCRIPTION
--- a/Documentation/cmd-close-connection.txt
+++ b/Documentation/cmd-close-connection.txt
@ -4,8 +4,9 @@
 gerrit close-connection - Close the specified SSH connection

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit close-connection' <SESSION_ID>
+_ssh_ -p <port> <host> _gerrit close-connection_ <SESSION_ID>
   [--wait]
 --

--- a/Documentation/cmd-create-account.txt
+++ b/Documentation/cmd-create-account.txt
@ -4,8 +4,9 @@
 gerrit create-account - Create a new user account.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit create-account'
+_ssh_ -p <port> <host> _gerrit create-account_
  [--group <GROUP>]
  [--full-name <FULLNAME>]
  [--email <EMAIL>]
--- a/Documentation/cmd-create-branch.txt
+++ b/Documentation/cmd-create-branch.txt
@ -4,8 +4,9 @@
 gerrit create-branch - Create a new branch

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit create-branch'
+_ssh_ -p <port> <host> _gerrit create-branch_
  <PROJECT>
  <NAME>
  <REVISION>
--- a/Documentation/cmd-create-group.txt
+++ b/Documentation/cmd-create-group.txt
@ -4,8 +4,9 @@
 gerrit create-group - Create a new account group.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit create-group'
+_ssh_ -p <port> <host> _gerrit create-group_
  [--owner <GROUP> | -o <GROUP>]
  [--description <DESC> | -d <DESC>]
  [--member <USERNAME>]
--- a/Documentation/cmd-create-project.txt
+++ b/Documentation/cmd-create-project.txt
@ -4,8 +4,9 @@
 gerrit create-project - Create a new hosted project

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit create-project'
+_ssh_ -p <port> <host> _gerrit create-project_
  [--owner <GROUP> ... | -o <GROUP> ...]
  [--parent <NAME> | -p <NAME> ]
  [--suggest-parents | -S ]
--- a/Documentation/cmd-flush-caches.txt
+++ b/Documentation/cmd-flush-caches.txt
@ -4,10 +4,11 @@
 gerrit flush-caches - Flush some/all server caches from memory

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit flush-caches' --all
-'ssh' -p <port> <host> 'gerrit flush-caches' --list
-'ssh' -p <port> <host> 'gerrit flush-caches' --cache <NAME> ...
+_ssh_ -p <port> <host> _gerrit flush-caches_ --all
+_ssh_ -p <port> <host> _gerrit flush-caches_ --list
+_ssh_ -p <port> <host> _gerrit flush-caches_ --cache <NAME> ...
 --

 == DESCRIPTION
--- a/Documentation/cmd-gc.txt
+++ b/Documentation/cmd-gc.txt
@ -4,8 +4,9 @@
 gerrit gc - Run the Git garbage collection

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit gc'
+_ssh_ -p <port> <host> _gerrit gc_
  [--all]
  [--show-progress]
  [--aggressive]
--- a/Documentation/cmd-gsql.txt
+++ b/Documentation/cmd-gsql.txt
@ -4,8 +4,9 @@
 gerrit gsql - Administrative interface to active database

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit gsql'
+_ssh_ -p <port> <host> _gerrit gsql_
  [--format {PRETTY | JSON | JSON_SINGLE}]
  [-c QUERY]
 --
--- a/Documentation/cmd-index-activate.txt
+++ b/Documentation/cmd-index-activate.txt
@ -4,8 +4,9 @@
 gerrit index activate - Activate the latest index version available

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit index activate <index>'
+_ssh_ -p <port> <host> _gerrit index activate <index>_
 --

 == DESCRIPTION
--- a/Documentation/cmd-index-changes.txt
+++ b/Documentation/cmd-index-changes.txt
@ -4,8 +4,9 @@
 gerrit index changes - Index one or more changes.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit index changes' <CHANGE> [<CHANGE> ...]
+_ssh_ -p <port> <host> _gerrit index changes_ <CHANGE> [<CHANGE> ...]
 --

 == DESCRIPTION
--- a/Documentation/cmd-index-start.txt
+++ b/Documentation/cmd-index-start.txt
@ -4,8 +4,9 @@
 gerrit index start - Start the online indexer

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit index start <index>'
+_ssh_ -p <port> <host> _gerrit index start_ <index>
 --

 == DESCRIPTION
--- a/Documentation/cmd-kill.txt
+++ b/Documentation/cmd-kill.txt
@ -4,8 +4,9 @@
 kill - Cancel or abort a background task

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'kill' <ID> ...
+_ssh_ -p <port> <host> _kill_ <ID> ...
 --

 == DESCRIPTION
--- a/Documentation/cmd-logging-ls-level.txt
+++ b/Documentation/cmd-logging-ls-level.txt
@ -6,8 +6,9 @@ gerrit logging ls-level - view the logging level
 gerrit logging ls - view the logging level

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit logging ls-level | ls'
+_ssh_ -p <port> <host> _gerrit logging ls-level_ | _ls_
  <NAME>
 --

--- a/Documentation/cmd-logging-set-level.txt
+++ b/Documentation/cmd-logging-set-level.txt
@ -6,8 +6,9 @@ gerrit logging set-level - set the logging level
 gerrit logging set - set the logging level

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit logging set-level | set'
+_ssh_ -p <port> <host> _gerrit logging set-level_ | _set_
  <LEVEL>
  <NAME>
 --
--- a/Documentation/cmd-ls-groups.txt
+++ b/Documentation/cmd-ls-groups.txt
@ -4,8 +4,9 @@
 gerrit ls-groups - List groups visible to caller

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ls-groups'
+_ssh_ -p <port> <host> _gerrit ls-groups_
  [--project <NAME> | -p <NAME>]
  [--user <NAME> | -u <NAME>]
  [--owned]
--- a/Documentation/cmd-ls-members.txt
+++ b/Documentation/cmd-ls-members.txt
@ -4,8 +4,9 @@
 gerrit ls-members - Show members of a given group

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ls-members GROUPNAME'
+_ssh_ -p <port> <host> _gerrit ls-members_ GROUPNAME
  [--recursive]
 --

--- a/Documentation/cmd-ls-projects.txt
+++ b/Documentation/cmd-ls-projects.txt
@ -4,8 +4,9 @@
 gerrit ls-projects - List projects visible to caller

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ls-projects'
+_ssh_ -p <port> <host> _gerrit ls-projects_
  [--show-branch <BRANCH> ...]
  [--description | -d]
  [--tree | -t]
--- a/Documentation/cmd-ls-user-refs.txt
+++ b/Documentation/cmd-ls-user-refs.txt
@ -4,8 +4,9 @@
 gerrit ls-user-refs - List refs visible to a specific user

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ls-user-refs'
+_ssh_ -p <port> <host> _gerrit ls-user-refs_
  [--project PROJECT> | -p <PROJECT>]
  [--user <USER> | -u <USER>]
  [--only-refs-heads]
--- a/Documentation/cmd-plugin-enable.txt
+++ b/Documentation/cmd-plugin-enable.txt
@ -4,8 +4,9 @@
 plugin enable - Enable plugins.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin enable'
+_ssh_ -p <port> <host> _gerrit plugin enable_
  <NAME> ...
 --

--- a/Documentation/cmd-plugin-install.txt
+++ b/Documentation/cmd-plugin-install.txt
@ -6,8 +6,9 @@ plugin install - Install/Add a plugin.
 plugin add - Install/Add a plugin.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin install | add'
+_ssh_ -p <port> <host> _gerrit plugin install_ | _add_
  [--name <NAME> | -n <NAME>]
  - | <URL> | <PATH>
 --
--- a/Documentation/cmd-plugin-ls.txt
+++ b/Documentation/cmd-plugin-ls.txt
@ -4,8 +4,9 @@
 plugin ls - List the installed plugins.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin ls'
+_ssh_ -p <port> <host> _gerrit plugin ls_
  [--all | -a]
  [--format {text | json | json_compact}]
 --
--- a/Documentation/cmd-plugin-reload.txt
+++ b/Documentation/cmd-plugin-reload.txt
@ -4,8 +4,9 @@
 plugin reload - Reload/Restart plugins.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin reload'
+_ssh_ -p <port> <host> _gerrit plugin reload_
  <NAME> ...
 --

--- a/Documentation/cmd-plugin-remove.txt
+++ b/Documentation/cmd-plugin-remove.txt
@ -6,8 +6,9 @@ plugin remove - Disable plugins.
 plugin rm - Disable plugins.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin remove | rm'
+_ssh_ -p <port> <host> _gerrit plugin remove_ | _rm_
  <NAME> ...
 --

--- a/Documentation/cmd-query.txt
+++ b/Documentation/cmd-query.txt
@ -4,8 +4,9 @@
 gerrit query - Query the change database

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit query'
+_ssh_ -p <port> <host> _gerrit query_
  [--format {TEXT | JSON}]
  [--current-patch-set]
  [--patch-sets | --all-approvals]
--- a/Documentation/cmd-receive-pack.txt
+++ b/Documentation/cmd-receive-pack.txt
@ -4,8 +4,9 @@
 git-receive-pack - Receive what is pushed into the repository

 == SYNOPSIS
+[verse]
 --
-'git receive-pack'
+_git receive-pack_
  [--reviewer <address> | --re <address>]
  [--cc <address>]
  <project>
--- a/Documentation/cmd-rename-group.txt
+++ b/Documentation/cmd-rename-group.txt
@ -4,8 +4,9 @@
 gerrit rename-group - Rename an account group.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit rename-group'
+_ssh_ -p <port> <host> _gerrit rename-group_
  <GROUP>
  <NEWNAME>
 --
--- a/Documentation/cmd-review.txt
+++ b/Documentation/cmd-review.txt
@ -1,12 +1,12 @@
-gerrit review
-==============
+= gerrit review

 == NAME
 gerrit review - Apply reviews to one or more patch sets

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit review'
+_ssh_ -p <port> <host> _gerrit review_
  [--project <PROJECT> | -p <PROJECT>]
  [--branch <BRANCH> | -b <BRANCH>]
  [--message <MESSAGE> | -m <MESSAGE>]
--- a/Documentation/cmd-set-account.txt
+++ b/Documentation/cmd-set-account.txt
@ -4,14 +4,16 @@
 gerrit set-account - Change an account's settings.

 == SYNOPSIS
+[verse]
 --
-set-account [--full-name <FULLNAME>] [--active|--inactive] \
-            [--add-email <EMAIL>] [--delete-email <EMAIL> | ALL] \
-            [--preferred-email <EMAIL>] \
-            [--add-ssh-key - | <KEY>] \
-            [--delete-ssh-key - | <KEY> | ALL] \
-            [--http-password <PASSWORD>] \
-            [--clear-http-password] <USER>
+_ssh_ -p <port> <host> _gerrit set-account_
+  [--full-name <FULLNAME>] [--active|--inactive]
+  [--add-email <EMAIL>] [--delete-email <EMAIL> | ALL]
+  [--preferred-email <EMAIL>]
+  [--add-ssh-key - | <KEY>]
+  [--delete-ssh-key - | <KEY> | ALL]
+  [--http-password <PASSWORD>]
+  [--clear-http-password] <USER>
 --

 == DESCRIPTION
--- a/Documentation/cmd-set-head.txt
+++ b/Documentation/cmd-set-head.txt
@ -4,8 +4,9 @@
 gerrit set-head - Change a project's HEAD.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-head' <NAME>
+_ssh_ -p <port> <host> _gerrit set-head_ <NAME>
  --new-head <REF>
 --

--- a/Documentation/cmd-set-members.txt
+++ b/Documentation/cmd-set-members.txt
@ -4,8 +4,9 @@
 gerrit set-members - Set group members

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-members'
+_ssh_ -p <port> <host> _gerrit set-members_
  [--add USER ...]
  [--remove USER ...]
  [--include GROUP ...]
--- a/Documentation/cmd-set-project-parent.txt
+++ b/Documentation/cmd-set-project-parent.txt
@ -4,8 +4,9 @@
 gerrit set-project-parent - Change the project permissions are inherited from.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-project-parent'
+_ssh_ -p <port> <host> _gerrit set-project-parent_
  [--parent <NAME>]
  [--children-of <NAME>]
  [--exclude <NAME>]
--- a/Documentation/cmd-set-project.txt
+++ b/Documentation/cmd-set-project.txt
@ -4,8 +4,9 @@
 gerrit set-project - Change a project's settings.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-project'
+_ssh_ -p <port> <host> _gerrit set-project_
  [--description <DESC> | -d <DESC>]
  [--submit-type <TYPE> | -t <TYPE>]
  [--contributor-agreements <true|false|inherit>]
--- a/Documentation/cmd-set-reviewers.txt
+++ b/Documentation/cmd-set-reviewers.txt
@ -4,8 +4,9 @@
 gerrit set-reviewers - Add or remove reviewers to a change

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-reviewers'
+_ssh_ -p <port> <host> _gerrit set-reviewers_
  [--project <PROJECT> | -p <PROJECT>]
  [--add <REVIEWER> ... | -a <REVIEWER> ...]
  [--remove <REVIEWER> ... | -r <REVIEWER> ...]
--- a/Documentation/cmd-show-caches.txt
+++ b/Documentation/cmd-show-caches.txt
@ -5,8 +5,11 @@ gerrit show-caches
 gerrit show-caches - Display current cache statistics

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit show-caches' [--gc] [--show-jvm]
+_ssh_ -p <port> <host> _gerrit show-caches_
+  [--gc]
+  [--show-jvm]
 --

 == DESCRIPTION
--- a/Documentation/cmd-show-connections.txt
+++ b/Documentation/cmd-show-connections.txt
@ -4,8 +4,10 @@
 gerrit show-connections - Display active client SSH connections

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit show-connections' [--numeric | -n]
+_ssh_ -p <port> <host> _gerrit show-connections_
+  [--numeric | -n]
 --

 == DESCRIPTION
--- a/Documentation/cmd-show-queue.txt
+++ b/Documentation/cmd-show-queue.txt
@ -4,9 +4,10 @@
 gerrit show-queue - Display the background work queues, including replication

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit show-queue'
-'ssh' -p <port> <host> 'ps'
+_ssh_ -p <port> <host> _gerrit show-queue_
+_ssh_ -p <port> <host> _ps_
 --

 == DESCRIPTION
--- a/Documentation/cmd-stream-events.txt
+++ b/Documentation/cmd-stream-events.txt
@ -4,8 +4,9 @@
 gerrit stream-events - Monitor events occurring in real time

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit stream-events'
+_ssh_ -p <port> <host> _gerrit stream-events_
 --

 == DESCRIPTION
--- a/Documentation/cmd-suexec.txt
+++ b/Documentation/cmd-suexec.txt
@ -4,11 +4,12 @@
 suexec - Execute a command as any registered user account

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port>
+_ssh_ -p <port>
  -i SITE_PATH/etc/ssh_host_rsa_key
-  '"Gerrit Code Review@localhost"'
-  'suexec'
+  "Gerrit Code Review@localhost"
+  _suexec_
  --as <EMAIL>
  [--from HOST:PORT]
  [--]
--- a/Documentation/cmd-test-submit-rule.txt
+++ b/Documentation/cmd-test-submit-rule.txt
@ -4,8 +4,9 @@
 gerrit test-submit rule - Test prolog submit rules with a chosen changeset.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit test-submit rule'
+_ssh_ -p <port> <host> _gerrit test-submit_ rule
  [-s]
  [--no-filters]
  CHANGE
--- a/Documentation/cmd-test-submit-type.txt
+++ b/Documentation/cmd-test-submit-type.txt
@ -4,8 +4,9 @@
 gerrit test-submit type - Test prolog submit type with a chosen change.

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit test-submit type'
+_ssh_ -p <port> <host> _gerrit test-submit_ type
  [-s]
  [--no-filters]
  CHANGE
--- a/Documentation/cmd-version.txt
+++ b/Documentation/cmd-version.txt
@ -4,8 +4,9 @@
 gerrit version - Show the version of the currently executing Gerrit server

 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit version'
+_ssh_ -p <port> <host> _gerrit version_
 --

 == DESCRIPTION