Merge pull request #1069 from robertpanzer/fix/1068

Fixes #1068. Clarify execution order of extensions

CHANGELOG.adoc

@@ -23,6 +23,10 @@ Build Improvement::
 * Add Java17 to CI pipelines (@abelsromero) (#1055)
 * Improve pipelines to better display Asciidoctor test upstream (@abelsromero) (#1057)
 
+Documentation::
+
+* Clarify execution order for extensions (@rockyallen) (#1068)
+
 == 2.5.2 (2021-08-08)
 
 Improvement::

docs/modules/extensions/pages/conversion-process-overview.adoc

@@ -6,17 +6,18 @@ As any language processing tool, the process can be roughly split into three ste
 . Parsing: the raw sources content is read and analyzed to generate the internal representation, the AST (_abstract syntax tree_).
 . Processing: the AST is processed. For example to detect possible errors, add automatically generated content (toc), etc.
 . Output generation: once the final AST is set, it's again processed to generate the desired output.
-For example, a sub-section of the AST representing a title with a paragraph will be converted into it's correspondent HTML or PDF output.
+For example, a sub-section of the AST representing a title with a paragraph will be converted into its correspondent HTML or PDF output.
 
 NOTE: Some liberty is taken to make the process easier to understand.
 In reality, Asciidoctor has implementation details that divert from the 3 steps above.
 
-The different extension types are called in different steps of the conversion process in the order shown in the table.
-Within each type:
+The different extension types are called in different steps of the conversion process in the following order:
 
-* Prepocessors is called just before parsing.
-* Treeprocessors is called right before processing.
-* Block macro, inline macro, and block processors are called during processing in the order that they appear in the document.
-* Postprocessors are called before output generation.
-* Include and DocinfoProcessors are called in an arbitrary and changeable order during processing.
-In the case of Include processors, it is called whenever an `include::` is found.
+. Preprocessors are called when the parser requires the AsciiDoc source to parse.
+. IncludeProcessors are called whenever an `include::` directive is found while reading the AsciiDoc source.
+. BlockMacroProcessors and BlockProcessors are called while parsing in the order that they appear in the source document.
+. TreeProcessors are called after the document has been completely parsed into the Document tree right before processing.
+. InlineMacroProcessors are called during output generation in the order that they appear in the document.
+. DocinfoProcessors are called at the beginning of output generation if they add content to the header.
+  And they are called at the end of output generation if they add content to the footer.
+. Postprocessors are called after output generation before the content is written to the destination.