[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] org-manual: Describe export process flow
|
From: |
Matt |
|
Subject: |
Re: [PATCH] org-manual: Describe export process flow |
|
Date: |
Tue, 26 Dec 2023 22:56:00 +0100 |
|
User-agent: |
Zoho Mail |
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