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

[Thomas S. Dye]

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