[PATCH] org-manual: Describe export process flow

[Ihor Radchenko <yantar92@posteo.net>]

[-- Attachment #1: Type: text/plain, Size: 318 bytes --]

Hi,

I'd like to add a new section to Org mode manual.
The new section will describe all the steps performed by Org export
process. This should hopefully create a more clear picture on how
various export hooks and filters are used.

The patch is attached.
I'd appreciate feedback from people not familiar with ox.el.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual.org-Describe-export-flow.patch --]
[-- Type: text/x-patch, Size: 3477 bytes --]

From 57d290b710c85e0411855937e224d2cecdbd52da Mon Sep 17 00:00:00 2001
Message-ID: <57d290b710c85e0411855937e224d2cecdbd52da.1703600243.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Tue, 26 Dec 2023 15:15:23 +0100
Subject: [PATCH] doc/org-manual.org: Describe export flow

* doc/org-manual.org (Summary of the export process): Explain how the
export process is handled in Org mode.
---
 doc/org-manual.org | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 7db69cbb6..1a9432b4d 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16391,6 +16391,60 @@ ** Advanced Export Configuration
 :DESCRIPTION: Fine-tuning the export output.
 :END:
 
+*** Summary of the export process
+
+During export, Org mode processes the source Org buffer in multiple
+steps:
+
+1. The source Org mode buffer is copied into temporary throwaway
+   buffer that can be edited by export hooks
+2. ~org-export-before-processing-hook~ is executed (see [[*Export hooks]])
+3. All the =#+include= keywords are expanded
+4. All the commented headings are removed
+5. All the macros are replaced in buffer
+6. When ~org-export-use-babel~ is non-nil (default), all the src
+   blocks and babel calls that are not inside archived headings are
+   processed
+7. ~org-export-before-parsing-hook~ is executed (see [[*Export hooks]])
+8. Export option values are calculated, according to in-buffer
+   keywords, =#+BIND= keywords, buffer-local and global
+   customizations.
+9. Files contributing to bibliography are calculated
+10. ~org-export-filter-options-functions~ is executed
+11. The buffer is parsed, generating abstract syntax tree (AST)
+12. The AST is cleaned from buffer elements that should not be
+    exported:
+    - Heading are removed according to =SELECT_TAGS= and
+      =EXCLUDE_TAGS= export keywords; =task=, =inline=, =arch= export
+      options
+    - All the comments are removed
+    - Clocks, drawers, fixed-width environments, footnotes, latex
+      environments and fragments, node properties, planning lines,
+      property drawers, statistics cookies, and timestamps are removed
+      or kept according to the corresponding export options
+    - Table rows containing [[*Column Width and Alignment][width and alignment markers]] are removed
+    - Table columns containing [[*Advanced features][recalc marks]] are removed
+13. Environment variables are expanded in all the file links when
+    =expand-links= export option is set
+14. ~org-export-filter-parse-tree-functions~ is executed
+15. All the citations are processed according to the chosen citation
+    backend
+16. =#+print_bibliography= keywords are replaced with bibliography
+    listings
+17. AST is transcoded according to the chosen export backend
+    - The export happens recursively, depth-first
+    - Each transcoded AST node, as a string, is passed to the
+      corresponding export filter (see [[*Filters]])
+18. The transcoded AST body is formatted according to backend's
+    "inner" template
+19. The resulting body is passed to
+    ~org-export-filter-body-functions~
+20. The filtered body is formatted according to backend's outer
+    template
+21. The resulting output is processed by citation backend finalizer
+22. ~org-export-filter-final-output-functions~ are applied to the
+    final output
+
 *** Export hooks
 :PROPERTIES:
 :UNNUMBERED: notoc
-- 
2.42.0


[-- Attachment #3: Type: text/plain, Size: 225 bytes --]



-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>