diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 9316ecde..06960e77 100644 --- a/CHANGELOG.adoc +++ b/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:: diff --git a/docs/modules/extensions/pages/conversion-process-overview.adoc b/docs/modules/extensions/pages/conversion-process-overview.adoc index daedf7e8..6b6dac84 100644 --- a/docs/modules/extensions/pages/conversion-process-overview.adoc +++ b/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.