From: "Thomas S. Dye" <tsd@tsdye.online>
To: Ihor Radchenko <yantar92@posteo.net>
Cc: emacs-orgmode@gnu.org
Subject: Re: [PATCH] org-manual: Describe export process flow
Date: Tue, 26 Dec 2023 09:19:53 -1000 [thread overview]
Message-ID: <877cl069jp.fsf@tsdye.online> (raw)
In-Reply-To: <87wmt1dp1c.fsf@localhost>
Aloha Ihor,
Ihor Radchenko <yantar92@posteo.net> writes:
> 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.
I'm not too familiar with ox.el.
I edited mostly to use an active voice. I put author queries in
parentheses. I haven't paid attention to manual formatting
conventions.
IMO, more links would likely be helpful.
* Suggested revision
Org mode export is a multi-step process that works on a temporary
copy of the buffer as follows:
1. Execute ~org-export-before-processing-hook~ (see
[[*Hooks]]);
2. Expand =#+include= keywords;
3. Remove commented headings; (author: clarify whether the
body is also removed?)
4. Replace macros;
5. Export source code blocks, conditional on
~org-export-use-babel~ and, if
necessary, the individual ~exports~ header arguments (see
[[*Exporting Code Blocks]]);
6. Evaluate source code blocks (see [[*Evaluating Code
Blocks]]);
7. Execute ~org-export-before-parsing-hook~ (see [[*Hooks]]);
8. Calculate export option values according to in-buffer
keywords,
=#+BIND= keywords, and buffer-local and global
customizations;
9. Calculate (author: Determine instead of Calculate?)
bibliography file paths;
10. Execute ~org-export-filter-options-functions~;
11. Parse the temporary (author: is this correct?) buffer to
generate an
abstract syntax tree (AST);
12. Remove elements that will not be exported from the AST:
1. Headings according to =SELECT_TAGS= and =EXCLUDE_TAGS=
export
keywords, and =task=, =inline=, =arch= export options;
2. Comments;
3. Clocks, drawers, fixed-width environments, footnotes,
LaTeX environments and fragments, node properties,
planning lines, property drawers, statistics cookies, and
timestamps according to their corresponding export
options;
4. Table rows containing [[*Column Width and
Alignment][width and alignment markers]];
5. Table columns containing [[*Advanced features][recalc
marks]];
13. Expand environment variables in file links according to
the =expand-links= export option (author: are we still
operating on AST here?);
14. Execute ~org-export-filter-parse-tree-functions~ (author:
ditto);
15. Create bibliography listing(s) from citation(s) (author:
ditto);
16. Replace =+print_bibliography= keyword(s) with bibliography
listing(s) (author: ditto);
17. Transcode the AST according to export backend using
recursive, depth-first search, and passing each transcoded
node as a string to the export filter (see [[*Filters]]):
18. Format transcoded AST according to the backend's "inner"
template;
19. Execute ~org-export-filter-body-functions~ on the
transcoded and formatted AST;
20. Format the result according to the backend's "outer"
template;
21. Finalize bibliography listing(s) (author: correct?) and
citation(s); and
22. Execute ~org-export-filter-final-output-functions~.
Let me know if you have questions.
All the best,
Tom
--
Thomas S. Dye
https://tsdye.online/tsdye
next prev parent reply other threads:[~2023-12-26 19:37 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-12-26 14:19 [PATCH] org-manual: Describe export process flow Ihor Radchenko
2023-12-26 19:19 ` Thomas S. Dye [this message]
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=877cl069jp.fsf@tsdye.online \
--to=tsd@tsdye.online \
--cc=emacs-orgmode@gnu.org \
--cc=yantar92@posteo.net \
/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).