From: Matt <matt@excalamus.com>
To: "Ihor Radchenko" <yantar92@posteo.net>
Cc: "emacs-orgmode" <emacs-orgmode@gnu.org>,
"Thomas S. Dye" <tsd@tsdye.online>,
"Karthik Chikmagalur" <karthikchikmagalur@gmail.com>
Subject: Re: [PATCH v2] org-manual: Describe export process flow
Date: Wed, 27 Dec 2023 16:03:24 +0100 [thread overview]
Message-ID: <18cabcd4180.110e4d2ac424365.1929818377821430813@excalamus.com> (raw)
In-Reply-To: <87le9fep69.fsf@localhost>
---- 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
next prev parent reply other threads:[~2023-12-27 15:04 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-12-26 14:19 [PATCH] org-manual: Describe export process flow Ihor Radchenko
2023-12-26 19:19 ` Thomas S. Dye
2023-12-26 21:22 ` Karthik Chikmagalur
2023-12-26 21:56 ` Matt
2023-12-26 22:02 ` Matt
2023-12-27 13:43 ` [PATCH v2] " Ihor Radchenko
2023-12-27 15:03 ` Matt [this message]
2023-12-27 17:08 ` [PATCH v3] " Ihor Radchenko
2023-12-27 18:02 ` Matt
2023-12-28 12:06 ` [PATCH v4] " Ihor Radchenko
2023-12-28 15:29 ` Matt
2024-02-12 13:25 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=18cabcd4180.110e4d2ac424365.1929818377821430813@excalamus.com \
--to=matt@excalamus.com \
--cc=emacs-orgmode@gnu.org \
--cc=karthikchikmagalur@gmail.com \
--cc=tsd@tsdye.online \
--cc=yantar92@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).