From: Ihor Radchenko <yantar92@posteo.net>
To: emacs-orgmode@gnu.org
Subject: [PATCH] org-manual: Describe export process flow
Date: Tue, 26 Dec 2023 14:19:43 +0000 [thread overview]
Message-ID: <87wmt1dp1c.fsf@localhost> (raw)
[-- 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>
next reply other threads:[~2023-12-26 14:17 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-12-26 14:19 Ihor Radchenko [this message]
2023-12-26 19:19 ` [PATCH] org-manual: Describe export process flow Thomas S. Dye
2023-12-26 21:22 ` Karthik Chikmagalur
2023-12-26 21:56 ` Matt
2023-12-26 22:02 ` Matt
2023-12-27 13:43 ` [PATCH v2] " Ihor Radchenko
2023-12-27 15:03 ` Matt
2023-12-27 17:08 ` [PATCH v3] " Ihor Radchenko
2023-12-27 18:02 ` Matt
2023-12-28 12:06 ` [PATCH v4] " Ihor Radchenko
2023-12-28 15:29 ` Matt
2024-02-12 13:25 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87wmt1dp1c.fsf@localhost \
--to=yantar92@posteo.net \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).