resolves #43 document attribute list parsing in detail

Authored by: David Jencks <djencks@apache.org>

CHANGELOG.adoc

@@ -12,6 +12,7 @@ Fixed::
 
 Added::
 * Add example of how to select all lines outside of tagged regions and lines inside a specific tagged region
+* Document attribute list parsing in detail (#43)
 
 Changed::
 * Clarify the rules for include tag filtering; emphasize that the wildcards can only be used once

modules/attributes/pages/positional-and-named-attributes.adoc

@@ -7,12 +7,15 @@ Let's break down the difference between positional and named attributes.
 
 // tag::pos[]
 Values placed in a specific order in an attribute list don't require an attribute name.
-The attribute that the value is assigned to depends on the type of the element:
+The attribute that the value is assigned to depends on the type of the element.
+Here are some examples:
 
 * `icon:` (1) size
 * `image:` and `image::` (1) alt text, (2) width, (3) height
 * Delimited blocks: (1) block name (aka style)
-* Other inline quoted text: (1) role
+* Other inline quoted text: (1) role and ID shorthand
+* `link:` and `xref:` (1) linked text
+* Custom blocks and macros can specify positional attributes
 
 For example, the following two image macros are equivalent.
 
@@ -56,3 +59,23 @@ No special processing is performed, except for attribute reference expansion, if
 
 If the attribute value contains the same quote character being used to enclose the value, escape the quote character in the value by prefixing it with a backslash (e.g., `title="\"Dark Horse\" is a song by George Harrison"`).
 // end::subs[]
+
+== Attribute list parsing
+
+The exact rules for determining whether an attribute is positional, and what defines the boundaries of an individual attribute, are defined below.
+
+A `name` consists of a word character (letter or numeral) followed by any number of word characters, `.` charactes, or `-` characters, followed by something else (including the end of the string)
+
+* Parsing an attribute proceeds from the beginning of the attribute list string or after a previously recognized delimiter (`,`).
+* Blank space is skipped.
+* If a valid attribute name is found, and it is followed by an equals sign (=), then the parser recognizes this as a named attribute.
+The text after the equals sign (=) and up to the next comma or end of list is taken as the attribute value.
+Spaces around the equals sign (=) are ignored.
+* Otherwise this is a positional attribute with value starting after the skipped blank space and ending before (optional) blank space preceding the next delimiter (`,`).
+* To parse the attribute value:
+** If the first character is not a quote, the string is read until the next delimiter or end of string.
+** If the first character is `"`, then the string is read until the next unescaped quote or, if there is no closing quote, the next delimiter.
+If there is a closing quote, the quotes are removed; if not, the initial quote is retained.
+** If the next character is `'` then the string is read until the next unescaped `'`, or if there is no closing `'`, the next delimiter.
+If there is a closing `'`, the enclosing `'` characters are removed; if not, the initial `'` is retained.
+If there is a closing `'` and the first character is not an escaped `'` substitutions are performed as described above.