[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH] org-manual: Describe export process flow

From: Thomas S. Dye
Subject: Re: [PATCH] org-manual: Describe export process flow
Date: Tue, 26 Dec 2023 09:19:53 -1000
User-agent: mu4e 1.6.10; emacs 27.1

Aloha Ihor,

Ihor Radchenko <yantar92@posteo.net> writes:


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;
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,
Thomas S. Dye

reply via email to

[Prev in Thread] Current Thread [Next in Thread]