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

[Matt]

  On Wed, 27 Dec 2023 14:41:32 +0100  Ihor Radchenko  wrote --- 
 
 > Thank you all for the feedback!

Thanks for taking the time to write and revise the patches.

You didn't explicitly ask for more feedback, so I hope the following feedback 
on the new patches is in order.

Both patches look good.  I see no issues with
v2-0001-doc-org-manual.org-Fix-some-obsolete-variable-nam.patch

For v2-0002-doc-org-manual.org-Describe-export-flow.patch here are
some quibbles:

> On high-level, the export process consists of 4 major steps:

I don't think "On high level" is necessary (it's also missing an 'a';
"On *a* high level").  "Major" implies high-level.

"The export process consists of 4 major steps:"

If you wanted to keep "high-level", you could replace major with it:

"The export process consists of 4 high-level steps:"

 > 2. Parse the buffer, converting plain Org markup into abstract syntax
 >tree (AST);

Missing "an":

"...converting plain Org markup into *an* abstract syntax..."

 > 5. Parse the accessible portion of the temporary buffer to generate
 >AST.  The AST is a nested list of lists representing Org syntax
 >elements

"...of the temporary buffer to generate *the* AST."

or

"...of the temporary buffer to generate *an* AST."

 >Past this point, modifications in the temporary buffer copy no
 >longer affect export; Org export works only with the AST;

Replace "in the" with "to the".

"no longer affect export" -> "no longer affect *the* export"

Replace "temporary buffer copy" with "temporary buffer" or "temporary
copy".

"Past this point, modifications to the temporary buffer no longer
affect the export; Org export works only with the AST;"

> 6. Remove elements that will not be exported from the AST:

"Remove elements that are not exported from the AST:"

or

"Remove elements not exported from the AST:"

 >- Headings according to =SELECT_TAGS= and =EXCLUDE_TAGS= export
 >  keywords, and =task=, =inline=, =arch= export options (see
 >  [[*Export Settings]]);

Remove comma after "keywords":

"Headings according to =SELECT_TAGS= and =EXCLUDE_TAGS= export
keywords and =task=, =inline=, =arch= export options (see [[*Export
Settings]]);"

 >- Clocks, drawers, fixed-width environments, footnotes, LaTeX
 >  environments and fragments, node properties, planning lines,
 >  property drawers, statistics cookies, timestamps, timestamps,
 >  etc according to =#+OPTIONS= keyword (see [[*Export Settings]]);

"timestamps" is written twice.

> - Table columns containing recalc marks (see [[*Advanced features]]).

This is indented two spaces more than the previous item.  Is that what you
want?

 > 7. Expand environment variables in file link AST nodes, according to
 >the =expand-links= export option (see [[*Export Settings]]);

Comma after "nodes" not necessary.

"Expand environment variables in file link AST nodes according to the
=expand-links= export option (see [[*Export Settings]]);"

 > 8. Execute ~org-export-filter-parse-tree-functions~.  These
 >functions can modify AST by side effect;

I would say "*the* AST" and make "side effect" plural:

"...can modify *the* AST by side effect*s*;"

 > 4. Convert the nodes with children to text, passing the nodes
 >themselves and their contents to the corresponding transcoders
 >and then to export filters (see [[*Filters]]).

Add a "the":

"...and then to *the* export filters (see [[*Filters]])."

-

Checking ox.el, I see that the commentary says,

";; See  for
;; more information."

Maybe also let maintainers know about this manual section:

"See:

"

-

Again, good work.  AFAIU, you used "affect" and "effect" correctly.
Breaking the big list into smaller ones makes it much easier to read.

--
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

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

[Ihor Radchenko]

Ihor Radchenko  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.

Thank you all for the feedback!
I am attaching revised version of the patch with most of the comments
addressed.

I will put more detailed responses inline.


"Thomas S. Dye"  writes:
> 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
> ...

I believe that I have addressed everything you commented on.

Karthik Chikmagalur  writes:
> - When exporting a sub-tree, at what stage of the export process is the
>   buffer narrowed to the sub-tree?

I added a clarification on subtree export now.

> - Are "inner" and "outer" templates described in the manual, and if they
>   are could you add a link to those sections when mentioning them in
>   this summary?  I only found references to the plist properties
>   BEAMER_INNER_THEME etc.

This is internal terminology. I changed the wording, expanding on what
inner and outer template do.

Matt  writes:
> 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.
> ...
> * Feedback 1:
> How are the functions not present in the patch handled?

- I fixed the obsolete variable names.
- `org-export-stack-mode-hook' is not directly relevant to the export
  process - it is for asynchronous export listing buffer
- Syntax-specific filters are applied according to the corresponding Org
  syntax element. I tried to make it more clear.
- Special filters, like `org-export-before-parsing-functions' are
  described separately. I think I have mentioned all of them.

> 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

We use "source block", "code block", and "source code block" across the
manual. Not "src block" though.
I went with "code block" in the patch.

I am not sure if it is necessary to standardize the above three terms.
They are all equally understandable I believe.

> 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"?

No idea. We do not have a consistency in the manual either.  I went with
";" as Thomas suggested.

> 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.

"transcoded" is closer to what we use in the code. I tried to use
"converted" in more general description, but still hint on the
internal terminology.

>From efee8fb5e8aca473b1b80aacc2b38951421225cc Mon Sep 17 00:00:00 2001
Message-ID: 
From: Ihor Radchenko 
Date: Wed, 27 Dec 2023 14:23:29 +0100
Subject: [PATCH v2 1/2] doc/org-manual.org: Fix some obsolete variable names

* doc/org-manual.org (Export hooks): Use the new
`org-export-before-processing-functions' and
`org-export-before-parsing-functions' instead of their obsolete
aliases.
---
 doc/org-manual.org | 12 +++-
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 23f250fa7..b35a83434 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16397,12 +16397,14 @@ *** Export hooks
 :END:
 
 #+vindex: org-export-before-processing-hook
+#+vindex: org-export-before-processing-functions
 #+vindex: org-export-before-parsing-hook
 The export process executes two hooks before the actual exporting
-begins.  The first hook, ~org-export-before-processing-hook~, runs
-before any expansions of macros, Babel code, and include keywords in
-the buffer.  The second hook, ~org-export-before-parsing-hook~, runs
-before the buffer is parsed.
+begins.  The first hook, ~org-export-before-processing-functions~,
+runs before any expansions of macros, Babel code, and include keywords
+in the buffer.  The second hook,
+~org-export-before-parsing-functions~, runs before the buffer is
+parsed.
 
 Functions added to these hooks are called with a single argument: the
 export backend actually used, as a symbol.  You may use them for
@@ -16421,7 +16423,7 @@ *** Export hooks
  ;; the docstring of `org-map-entries' for details.
  (setq org-map-continue-from (point)
 
-(add-hook 'org-export-before-parsing-hook #'my-headline-removal)
+(add-hook 'org-export-before-parsing-functions #'my-headline-removal)
 #+end_src
 
 *** Filters
-- 
2.42.0

>From