feat(parser): custom substitutions on paragraphs (#749)

Using multiple substitutions to parse the paragraph content
and support custom substitutions via the `subs` attribute.

Some grammar rules have been simplified. For example, the
content of a quoted text can only be other quoted texts or
plain characters.

Using "placeholder" elements to support parsing of complex
elements in which previously elements were identified. For
example, a link may contain quoted text as attributes, quoted
test may contain special characters, etc.

Also, introducing a new `ElementRole` type, since attributes
may contain special characters which would be rendered differently,
depending on the backend.

However, this may need more work in the future (expand to
other attributes with something generic?)

Sadly, all these changes also have an impact on the performances,
so further investigation may be required, to see if optimizations
can be found.

Fixes #597

Signed-off-by: Xavier Coulon <[email protected]>

LIMITATIONS.adoc

@@ -128,6 +128,28 @@ File inclusions are performed before the full parsing takes place. During this p
 If the file to include has an empty last line, it will be ignored, so it's always a good practice to include a blank line after the `include::` directive in the main document, to avoid side-effects during
 the "full" parsing.
 
+== Substitutions
+
+In "normal" paragraphs, Asciidoctor processes the content with the following substitutions, in the following order:
+
+1. Special characters
+2. Quotes
+3. Attribute references
+4. Replacements
+5. Inline macros
+6. Post replacements
+
+However, splitting the "Quotes" and "Inline Macros" in two distinct steps causes troubles in LibAsciidoc, when an inline macro is wrapped in quoted text, or when an inline macro contains quoted attributes. 
+As a consequence, in "normal" paragraphs, LibAsciidoc processes the content with the following substitutions, in the following order:
+
+1. Special characters
+2. Attribute references
+3. Replacements
+4. Quotes and Inline macros
+5. Post replacements
+
+
+
 == Symbols and Characters
 
 Markup for the mdash and arrow symbols is not recognized.

pkg/parser/comment_test.go

@@ -47,7 +47,7 @@ var _ = Describe("comments", func() {
 			It("single line comment within a paragraph", func() {
 				source := `a first line
 // A single-line comment.
-another line // with a comment`
+another line // not a comment`
 				expected := types.DraftDocument{
 					Blocks: []interface{}{
 						types.Paragraph{
@@ -64,7 +64,7 @@ another line // with a comment`
 								},
 								[]interface{}{
 									types.StringElement{
-										Content: "another line // with a comment",
+										Content: "another line // not a comment",
 									},
 								},
 							},