refactor(parser): apply attribute substitutions in final Document (by…

…tesparadise#457)

* refactor(parser): apply attribute substitutions in final Document

DocumentAttributeDeclaration, Substitution and Reset
blocks are processed while preparing the final
document.
As a consequence, final document is simpler to render,
but more processing needs to take place beforehand,
including the section id generation, the implicit usage of
the  'imagesdir' attribute while generating the image
location and the marker for the table of contents.

If an attribute was not declared and could not be sustituted, then
it is replace with its name surrounded by curly brackets.

also, removed some unused funcs

fixes bytesparadise#444

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

docs/design.adoc

@@ -1,12 +1,41 @@
 = Libasciidoc Design
 
-This document brifley explains how the library works, from parsing to rendering in HTML.
+This document brifley explains how the library works, from parsing a document to rendering in HTML.
+
+== Types
+
+A document contains blocks, which can have attributes, nested blocks and elements.
+
+Blocks are of the following types:
+
+- Section
+- Paragraph
+- Delimited block
+- Image
+- Table
+- List
+- File inclusion
+- Comment
+
+Tables, lists and delimited blocks can contain other blocks.
+
+Blocks can also contain elements, such as:
+
+- quoted text
+- links
+- (inline) images
+- passthrough text
+- foot notes
+- user-defined macros
+
+Attributes are set within squate brackets (`[]`), both on top of the document blocks and as a suffix of elements.
+
 
 == Parsing the document
 
-The first step is to parse a document. The parser (generated after the link:../pkg/parser/parser.peg[grammar] returns a "draft document" in which the sections are not embedded in a hierarchical manner, other blocks are also not attached to their parent section, blanklines are present, but in which the file inclusions have been processed. 
+First, the internal parser (generated after the link:../pkg/parser/parser.peg[grammar] returns a "draft document" in which the sections are not embedded in a hierarchical manner, other blocks are also not attached to their parent section, blanklines are present, document attributes declarations, substitutions and reset macros are also present, and file inclusions have been processed. 
 
-This so-called "draft document" is then processed to return a "final document" in which the sections are in a hierarchical organization, with their blocks (paragraphs, delimited blocks, etc.) attached to them. Also, all document attribute substitutions have been processed (sometimes resulting in new elements such as links). Blank line elements have been stripped off, too.
+This so-called "draft document" is then processed to return a "final document" in which the sections are organized in a hierarchical manner with their child blocks (paragraphs, delimited blocks, etc.) attached to them. Also, all document attribute substitutions have been processed (sometimes resulting in new elements such as links) and removed. Blank line elements have been stripped off, too (except in delimited blocks).
 
 == HTMl5 Rendering