update documentation for attribute cli argument

3 files changed, 19 insertions, 16 deletions

diff --git a/lib/asciidoctor/cli/options.rb b/lib/asciidoctor/cli/options.rb
index 36c61527..2f0a2e7c 100644
--- a/lib/asciidoctor/cli/options.rb
+++ b/lib/asciidoctor/cli/options.rb
@@ -78,9 +78,10 @@ Example: asciidoctor -b html5 source.asciidoc
           opts.on('-C', '--compact', 'compact the output by removing blank lines (default: false)') do
             self[:compact] = true
           end
-          opts.on('-a', '--attribute key1=value,key2=value2,...', Array,
-                  'a list of attributes, in the form key or key=value pair, to set on the document',
-                  'these attributes take precedence over attributes defined in the source file') do |attribs|
+          opts.on('-a', '--attribute key[=value],key2[=value2],...', Array,
+                  'a list of document attributes to set in the form of key, key! or key=value pair',
+                  'unless @ is appended to the value, these attributes take precedence over attributes',
+                  'defined in the source document') do |attribs|
             attribs.each do |attrib|
               key, val = attrib.split '=', 2
               self[:attributes][key] = val || ''
diff --git a/man/asciidoctor.1 b/man/asciidoctor.1
index f9973f4c..f1b76b1b 100644
--- a/man/asciidoctor.1
+++ b/man/asciidoctor.1
@@ -2,12 +2,12 @@
 .\"     Title: asciidoctor
 .\"    Author: [see the "AUTHORS" section]
 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 05/15/2013
+.\"      Date: 05/30/2013
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "ASCIIDOCTOR" "1" "05/15/2013" "\ \&" "\ \&"
+.TH "ASCIIDOCTOR" "1" "05/30/2013" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -71,20 +71,22 @@ when Asciidoctor is invoked using this script\&.
 Define, override or delete a document attribute\&. Command\-line attributes take precedence over attributes defined in the source file\&.
 .sp
 \fIATTRIBUTE\fR
-is formatted as a key\-value pair, in the form
-\fINAME=VALUE\fR\&. Values containing spaces should be enclosed in double\-quote characters\&. Alternate acceptable forms are
+is normally formatted as a key\-value pair, in the form
+\fINAME=VALUE\fR\&. Alternate acceptable forms are
 \fINAME\fR
-(the
+(where the
 \fIVALUE\fR
 defaults to an empty string),
 \fINAME!\fR
-(deletes the
+(unassigns the
 \fINAME\fR
 attribute) and
 \fINAME=VALUE@\fR
-(does not override
+(where
+\fIVALUE\fR
+does not override value of
 \fINAME\fR
-attribute if already defined in the source file)\&.
+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\&.
 .RE
diff --git a/man/asciidoctor.ad b/man/asciidoctor.ad
index 6317c32d..7cdb4281 100644
--- a/man/asciidoctor.ad
+++ b/man/asciidoctor.ad
@@ -53,11 +53,11 @@ Document Settings
     Define, override or delete a document attribute. Command-line attributes
     take precedence over attributes defined in the source file.
 +
-'ATTRIBUTE' is formatted as a key-value pair, in the form 'NAME=VALUE'. Values
-containing spaces should be enclosed in double-quote characters.  Alternate
-acceptable forms are 'NAME' (the 'VALUE' defaults to an empty string), 'NAME!'
-(deletes the 'NAME' attribute) and 'NAME=VALUE@' (does not override 'NAME'
-attribute if already defined in the source file).
+'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). Values containing spaces should be enclosed in quotes.
 +
 This option may be specified more than once.