This looks useful. My only understanding of the problem this addresses is what you wrote:
> create a more clear picture on how various export hooks and filters > are used. With this understanding, my first question was, "What hooks exist?" I see that [[https://www.gnu.org/software/emacs/manual/html_node/org/Advanced-Export-Configuration.html][Advanced Export Configuration]] gives only ~org-export-before-processing-hook~ and ~org-export-before-parsing-hook~. The section below it gives a table of filters. Here are all the hooks and functions for org-export (via =C-h v org-export--hooks TAB= and =C-h v org-export--function TAB=). I see 59 of them. | Hooks | Manual (60f357e8b) | Patch | |-------------------------------------------------+--------------------+-------| | org-export-before-processing-hook (obsolete) | X | X | | org-export-before-parsing-hook | X | X | | org-export-stack-mode-hook | | | | org-export-filter-options-functions | X | X | | org-export-filter-parse-tree-functions | X | X | | org-export-filter-body-functions | X | X | | org-export-filter-final-output-functions | X | X | | org-export-before-parsing-functions | | | | org-export-before-processing-functions | | | | org-export-filter-babel-call-functions | X | | | org-export-filter-bold-functions | X | | | org-export-filter-center-block-functions | X | | | org-export-filter-clock-functions | X | | | org-export-filter-code-functions | X | | | org-export-filter-diary-sexp-functions | X | | | org-export-filter-drawer-functions | X | | | org-export-filter-dynamic-block-functions | X | | | org-export-filter-entity-functions | X | | | org-export-filter-example-block-functions | X | | | org-export-filter-export-block-functions | X | | | org-export-filter-export-snippet-functions | X | | | org-export-filter-fixed-width-functions | X | | | org-export-filter-footnote-definition-functions | X | | | org-export-filter-footnote-reference-functions | X | | | org-export-filter-headline-functions | X | | | org-export-filter-horizontal-rule-functions | X | | | org-export-filter-inline-babel-call-functions | X | | | org-export-filter-inline-src-block-functions | X | | | org-export-filter-inlinetask-functions | X | | | org-export-filter-italic-functions | X | | | org-export-filter-item-functions | X | | | org-export-filter-keyword-functions | X | | | org-export-filter-latex-environment-functions | X | | | org-export-filter-latex-fragment-functions | X | | | org-export-filter-line-break-functions | X | | | org-export-filter-link-functions | X | | | org-export-filter-node-property-functions | X | | | org-export-filter-paragraph-functions | X | | | org-export-filter-plain-list-functions | X | | | org-export-filter-plain-text-functions | X | | | org-export-filter-planning-functions | X | | | org-export-filter-property-drawer-functions | X | | | org-export-filter-quote-block-functions | X | | | org-export-filter-radio-target-functions | X | | | org-export-filter-section-functions | X | | | org-export-filter-special-block-functions | X | | | org-export-filter-src-block-functions | X | | | org-export-filter-statistics-cookie-functions | X | | | org-export-filter-strike-through-functions | X | | | org-export-filter-subscript-functions | X | | | org-export-filter-superscript-functions | X | | | org-export-filter-table-cell-functions | X | | | org-export-filter-table-functions | X | | | org-export-filter-table-row-functions | X | | | org-export-filter-target-functions | X | | | org-export-filter-timestamp-functions | X | | | org-export-filter-underline-functions | X | | | org-export-filter-verbatim-functions | X | | | org-export-filter-verse-block-functions | X | | |-------------------------------------------------+--------------------+-------| * Feedback 1: How are the functions not present in the patch handled? I have no clue if they're relevant here or if someone would be confused by their absence. I only noticed that some of them were used in the patch and that the purpose of the patch also deals with filters. * Feedback 2: If I read the patch correctly, the it places the summary *before* the "Export hooks" section. This means that the summary will refer to the hooks before they're introduced (AFAICT, they're only ever mentioned in the "Export hooks" section). The summary should come after the hooks. Maybe before "Extending an existing back-end" or before the next Chapter (Publishing)? * Feedback 3: These are nitpicky things. > 1. The source Org mode buffer is copied into temporary throwaway > buffer that can be edited by export hooks "throwaway" is unnecessary because "temporary" implies it. > 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 I would write out "src" as "source". Do we have an official way to refer to source blocks? For example, we standardize on "Org": https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/doc/Documentation_Standards.org#n47 Capitalize "babel" since it's a name. > 8. Export option values are calculated, according to in-buffer > keywords, =#+BIND= keywords, buffer-local and global > customizations. The first comma is not necessary. The option values are calculated according to the list that follows (in-buffer keywords, BIND, etc.). Remove the trailing period or add periods to all the others. I tend leave the period of the last sentence of a list. I'm not sure of a style guide that recommends one or the other. Maybe someone knows what's "right"? > - Heading are removed according to =SELECT_TAGS= and > =EXCLUDE_TAGS= export keywords; =task=, =inline=, =arch= export > options "Heading" should be "Headings" > 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 Maybe use "converted" instead of "transcoded"? I'm a native speaker but I wonder if "converted" is a simpler word for people who aren't. The sentence is simpler by removing the commas and rearranging, "Each transcoded AST node is passed as a string to the corresponding export filter (see [[*Filters]])"" What's an "inner" template and why does that matter? > 20. The filtered body is formatted according to backend's outer > template What's an "outer" template and why does it matter? Should "outer" be quoted like "inner" was? Or, should "inner" be unquoted? > 21. The resulting output is processed by citation backend finalizer "Finalizer" is vague. What's its significance? Does it correspond to a function the end-user might look up? Overall, great work! For each "negative" bit of feedback, there were at least two things that deserve "positive" comments. I saw no spelling errors, you wrote out abbreviations (AST) before using them, and there are no voice issues. Everything was to the point. At first I was confused why this is being added to the manual and not to Worg. However, after reading it more thoroughly, I believe it will be a welcome and helpful addition to the manual. The export process is complex! -- Matt Trzcinski Emacs Org contributor (ob-shell) Learn more about Org mode at https://orgmode.org Support Org development at https://liberapay.com/org-mode
