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 <https://orgmode.org/worg/dev/org-export-reference.html> for
;; more information."

Maybe also let maintainers know about this manual section:

"See:
<https://orgmode.org/worg/dev/org-export-reference.html>
<link to Summary of the export process>"

-----

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