[rubygems/rubygems] Improve bundle plugin documentation

Make synopsis, subcommands, and CLI flags use a format consistent with
the other docs, and also reword some sentences for clarify.

ruby/rubygems@9272169ad0

Author: deivid-rodriguez

lib/bundler/man/bundle-plugin.1

@@ -4,7 +4,7 @@
 .SH "NAME"
 \fBbundle\-plugin\fR \- Manage Bundler plugins
 .SH "SYNOPSIS"
-\fBbundle plugin\fR install PLUGINS [\-\-source=\fISOURCE\fR] [\-\-version=\fIversion\fR] [\-\-git=\fIgit\-url\fR] [\-\-branch=\fIbranch\fR|\-\-ref=\fIrev\fR] [\-\-path=\fIpath\fR]
+\fBbundle plugin\fR install PLUGINS [\-\-source=SOURCE] [\-\-version=VERSION] [\-\-git=GIT] [\-\-branch=BRANCH|\-\-ref=REF] [\-\-local\-git=LOCAL_GIT] [\-\-path=PATH]
 .br
 \fBbundle plugin\fR uninstall PLUGINS [\-\-all]
 .br
@@ -16,18 +16,23 @@ You can install, uninstall, and list plugin(s) with this command to extend funct
 .SH "SUB\-COMMANDS"
 .SS "install"
 Install the given plugin(s)\.
+.P
+For example, \fBbundle plugin install bundler\-graph\fR will install bundler\-graph gem from globally configured sources (defaults to RubyGems\.org)\. Note that the global source specified in Gemfile is ignored\.
+.P
+\fBOPTIONS\fR
 .TP
-\fBbundle plugin install bundler\-graph\fR
-Install bundler\-graph gem from globally configured sources (defaults to RubyGems\.org)\. The global source, specified in source in Gemfile is ignored\.
-.TP
-\fBbundle plugin install bundler\-graph \-\-source https://example\.com\fR
-Install bundler\-graph gem from example\.com\. The global source, specified in source in Gemfile is not considered\.
+\fB\-\-source=SOURCE\fR
+Install the plugin gem from a specific source, rather than from globally configured sources\.
+.IP
+Example: \fBbundle plugin install bundler\-graph \-\-source https://example\.com\fR
 .TP
-\fBbundle plugin install bundler\-graph \-\-version 0\.2\.1\fR
-You can specify the version of the gem via \fB\-\-version\fR\.
+\fB\-\-version=VERSION\fR
+Specify a version of the plugin gem to install via \fB\-\-version\fR\.
+.IP
+Example: \fBbundle plugin install bundler\-graph \-\-version 0\.2\.1\fR
 .TP
-\fBbundle plugin install bundler\-graph \-\-git https://github\.com/rubygems/bundler\-graph\fR
-Install bundler\-graph gem from Git repository\. You can use standard Git URLs like:
+\fB\-\-git=GIT\fR
+Install the plugin gem from a Git repository\. You can use standard Git URLs like:
 .IP
 \fBssh://[user@]host\.xz[:port]/path/to/repo\.git\fR
 .br
@@ -37,12 +42,24 @@ Install bundler\-graph gem from Git repository\. You can use standard Git URLs l
 .br
 \fBfile:///path/to/repo\fR
 .IP
-When you specify \fB\-\-git\fR, you can use \fB\-\-branch\fR or \fB\-\-ref\fR to specify any branch, tag, or commit hash (revision) to use\.
+Example: \fBbundle plugin install bundler\-graph \-\-git https://github\.com/rubygems/bundler\-graph\fR
 .TP
-\fBbundle plugin install bundler\-graph \-\-path \.\./bundler\-graph\fR
-Install bundler\-graph gem from a local path\.
+\fB\-\-branch=BRANCH\fR
+When you specify \fB\-\-git\fR, you can use \fB\-\-branch\fR to use\.
 .TP
-\fBbundle plugin install bundler\-graph \-\-local\-git \.\./bundler\-graph\fR
+\fB\-\-ref=REF\fR
+When you specify \fB\-\-git\fR, you can use \fB\-\-ref\fR to specify any tag, or commit hash (revision) to use\.
+.TP
+\fB\-\-path=PATH\fR
+Install the plugin gem from a local path\.
+.IP
+Example: \fBbundle plugin install bundler\-graph \-\-path \.\./bundler\-graph\fR
+.TP
+\fB\-\-local\-git=LOCAL_GIT\fR
+Install the plugin gem from a local Git repository\.
+.IP
+Example: \fBbundle plugin install bundler\-graph \-\-local\-git \.\./bundler\-graph\fR\.
+.IP
 This option is deprecated in favor of \fB\-\-git\fR\.
 .SS "uninstall"
 Uninstall the plugin(s) specified in PLUGINS\.

lib/bundler/man/bundle-plugin.1.ronn

@@ -3,9 +3,10 @@ bundle-plugin(1) -- Manage Bundler plugins
 
 ## SYNOPSIS
 
-`bundle plugin` install PLUGINS [--source=<SOURCE>] [--version=<version>]
-                              [--git=<git-url>] [--branch=<branch>|--ref=<rev>]
-                              [--path=<path>]<br>
+`bundle plugin` install PLUGINS [--source=SOURCE] [--version=VERSION]
+                              [--git=GIT] [--branch=BRANCH|--ref=REF]
+                              [--local-git=LOCAL_GIT]
+                              [--path=PATH]<br>
 `bundle plugin` uninstall PLUGINS [--all]<br>
 `bundle plugin` list<br>
 `bundle plugin` help [COMMAND]
@@ -20,29 +21,49 @@ You can install, uninstall, and list plugin(s) with this command to extend funct
 
 Install the given plugin(s).
 
-* `bundle plugin install bundler-graph`:
-  Install bundler-graph gem from globally configured sources (defaults to RubyGems.org). The global source, specified in source in Gemfile is ignored.
+For example, `bundle plugin install bundler-graph` will install bundler-graph
+gem from globally configured sources (defaults to RubyGems.org). Note that the
+global source specified in Gemfile is ignored.
 
-* `bundle plugin install bundler-graph --source https://example.com`:
-  Install bundler-graph gem from example.com. The global source, specified in source in Gemfile is not considered.
+**OPTIONS**
+
+* `--source=SOURCE`:
+  Install the plugin gem from a specific source, rather than from globally configured sources.
+
+  Example: `bundle plugin install bundler-graph --source https://example.com`
 
-* `bundle plugin install bundler-graph --version 0.2.1`:
-  You can specify the version of the gem via `--version`.
+* `--version=VERSION`:
+  Specify a version of the plugin gem to install via `--version`.
 
-* `bundle plugin install bundler-graph --git https://github.com/rubygems/bundler-graph`:
-  Install bundler-graph gem from Git repository. You can use standard Git URLs like:
+  Example: `bundle plugin install bundler-graph --version 0.2.1`
+
+* `--git=GIT`:
+  Install the plugin gem from a Git repository. You can use standard Git URLs like:
 
   `ssh://[user@]host.xz[:port]/path/to/repo.git`<br>
   `http[s]://host.xz[:port]/path/to/repo.git`<br>
   `/path/to/repo`<br>
   `file:///path/to/repo`
 
-  When you specify `--git`, you can use `--branch` or `--ref` to specify any branch, tag, or commit hash (revision) to use.
+  Example: `bundle plugin install bundler-graph --git https://github.com/rubygems/bundler-graph`
+
+* `--branch=BRANCH`:
+  When you specify `--git`, you can use `--branch`  to use.
+
+* `--ref=REF`:
+  When you specify `--git`, you can use `--ref` to specify any tag, or commit
+  hash (revision) to use.
+
+* `--path=PATH`:
+  Install the plugin gem from a local path.
+
+  Example: `bundle plugin install bundler-graph --path ../bundler-graph`
+
+* `--local-git=LOCAL_GIT`:
+  Install the plugin gem from a local Git repository.
 
-* `bundle plugin install bundler-graph --path ../bundler-graph`:
-  Install bundler-graph gem from a local path.
+  Example: `bundle plugin install bundler-graph --local-git ../bundler-graph`.
 
-* `bundle plugin install bundler-graph --local-git ../bundler-graph`:
   This option is deprecated in favor of `--git`.
 
 ### uninstall