improve documentation for the `-a` CLI option [skip ci]

- reword description
- explain that `@` modifier can be placed at end of name as alternative to end of value

4 files changed, 20 insertions, 14 deletions

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 67ca39aa..5bc4f1c1 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -13,6 +13,12 @@ endif::[]
 This document provides a high-level view of the changes introduced in Asciidoctor by release.
 For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
 
+== Unreleased
+
+Improvements::
+
+  * improve documentation for the `-a` CLI option; explain that `@` modifier can be placed at end of name as alternative to end of value
+
 == 2.0.6 (2019-04-04) - @mojavelinux
 
 Bug Fixes::
diff --git a/lib/asciidoctor/cli/options.rb b/lib/asciidoctor/cli/options.rb
index daaeeb16..66ff244d 100644
--- a/lib/asciidoctor/cli/options.rb
+++ b/lib/asciidoctor/cli/options.rb
@@ -80,13 +80,13 @@ module Asciidoctor
                   'specify eRuby implementation to use when rendering custom ERB templates: [erb, erubis] (default: erb)') do |eruby|
             self[:eruby] = eruby
           end
-          opts.on('-a', '--attribute key[=value]', 'a document attribute to set in the form of key, key! or key=value pair',
-                  'unless @ is appended to the value, this attributes takes precedence over attributes',
-                  'defined in the source document') do |attr|
+          opts.on('-a', '--attribute name[=value]', 'a document attribute to set in the form of name, name!, or name=value pair',
+                  'this attribute takes precedence over the same attribute defined in the source document',
+                  'unless either the name or value ends in @ (i.e., name@=value or name=value@)') do |attr|
             next if (attr = attr.rstrip).empty? || attr == '='
             attr = attr.encode UTF_8 unless attr.encoding == UTF_8
-            key, _, val = attr.partition '='
-            self[:attributes][key] = val
+            name, _, val = attr.partition '='
+            self[:attributes][name] = val
           end
           opts.on('-T', '--template-dir DIR', 'a directory containing custom converter templates that override the built-in converter (requires tilt gem)',
                   'may be specified multiple times') do |template_dir|
diff --git a/man/asciidoctor.1 b/man/asciidoctor.1
index 2dc45dc7..ffbeabee 100644
--- a/man/asciidoctor.1
+++ b/man/asciidoctor.1
@@ -2,12 +2,12 @@
 .\"     Title: asciidoctor
 .\"    Author: Dan Allen, Sarah White, Ryan Waldron
 .\" Generator: Asciidoctor 2.0.6
-.\"      Date: 2019-04-04
+.\"      Date: 2019-04-07
 .\"    Manual: Asciidoctor Manual
 .\"    Source: Asciidoctor 2.0.6
 .\"  Language: English
 .\"
-.TH "ASCIIDOCTOR" "1" "2019-04-04" "Asciidoctor 2.0.6" "Asciidoctor Manual"
+.TH "ASCIIDOCTOR" "1" "2019-04-07" "Asciidoctor 2.0.6" "Asciidoctor Manual"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -65,11 +65,11 @@ If not set, the safe mode level defaults to \fIunsafe\fP when Asciidoctor is inv
 .sp
 \fB\-a, \-\-attribute\fP=\fIATTRIBUTE\fP
 .RS 4
-Define, override or delete a document attribute.
-Command\-line attributes take precedence over attributes defined in the source file unless the value ends with \fI@\fP.
+Define, override, or unset a document attribute.
+Command\-line attributes take precedence over attributes defined in the source file unless either the name or value ends in \fI@\fP.
 .sp
 \fIATTRIBUTE\fP is normally formatted as a key\-value pair, in the form \fINAME=VALUE\fP.
-Alternate acceptable forms are \fINAME\fP (where the \fIVALUE\fP defaults to an empty string), \fINAME!\fP (unassigns the \fINAME\fP attribute) and \fINAME=VALUE@\fP (where \fIVALUE\fP does not override value of \fINAME\fP attribute if it\(cqs already defined in the source document).
+Alternate forms are \fINAME\fP (where the \fIVALUE\fP defaults to an empty string), \fINAME!\fP (unsets the \fINAME\fP attribute), and \fINAME=VALUE@\fP (or \fINAME@=VALUE\fP) (where \fIVALUE\fP does not override the \fINAME\fP attribute if it\(cqs already defined in the source document).
 Values containing spaces should be enclosed in quotes.
 .sp
 This option may be specified more than once.
@@ -265,4 +265,4 @@ Dan Allen
 .sp
 Sarah White
 .sp
-Ryan Waldron
\ No newline at end of file
+Ryan Waldron
diff --git a/man/asciidoctor.adoc b/man/asciidoctor.adoc
index 55fa61a4..ac0a9267 100644
--- a/man/asciidoctor.adoc
+++ b/man/asciidoctor.adoc
@@ -42,11 +42,11 @@ If _FILE_ is _-_ then the AsciiDoc source is read from standard input.
 === Document Settings
 
 *-a, --attribute*=_ATTRIBUTE_::
-  Define, override or delete a document attribute.
-  Command-line attributes take precedence over attributes defined in the source file unless the value ends with _@_.
+  Define, override, or unset a document attribute.
+  Command-line attributes take precedence over attributes defined in the source file unless either the name or value ends in _@_.
 +
 _ATTRIBUTE_ is normally formatted as a key-value pair, in the form _NAME=VALUE_.
-Alternate acceptable forms are _NAME_ (where the _VALUE_ defaults to an empty string), _NAME!_ (unassigns the _NAME_ attribute) and _NAME=VALUE@_ (where _VALUE_ does not override value of _NAME_ attribute if it's already defined in the source document).
+Alternate forms are _NAME_ (where the _VALUE_ defaults to an empty string), _NAME!_ (unsets the _NAME_ attribute), and _NAME=VALUE@_ (or _NAME@=VALUE_) (where _VALUE_ does not override the _NAME_ attribute if it's already defined in the source document).
 Values containing spaces should be enclosed in quotes.
 +
 This option may be specified more than once.