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

[Ihor Radchenko]

Ihor Radchenko  writes:

> ... See the attached.
> I added reference to the manual in `org-export-as' docstring and made it
> explicit that the manual section is related to `org-export-as' by adding
> #+findex entry.

Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=1ff72e091
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=46cf76259
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=1087a7b4a
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=f9fc9d95c
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=a70f216e3

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

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

[Matt]

  On Thu, 28 Dec 2023 13:05:27 +0100  Ihor Radchenko  wrote --- 

 > See the attached.

All looks good to me.  

--
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 v4] org-manual: Describe export process flow

[Ihor Radchenko]

Matt  writes:

> I was making a different point.  I was trying to say that it may be a
> good idea for the ox.el commentary section to specifically reference
> the new manual section (next to where it references Worg).

Makes sense. See the attached.
I added reference to the manual in `org-export-as' docstring and made it
explicit that the manual section is related to `org-export-as' by adding
#+findex entry.

>From b17d57c1afeb160783da36647f56462ee67c3558 Mon Sep 17 00:00:00 2001
Message-ID: 
From: Ihor Radchenko 
Date: Wed, 27 Dec 2023 14:23:29 +0100
Subject: [PATCH v4 1/5] 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 ff1b9cffb..377706ee7 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 b195caf687793af228a2ea9a484f2fb8cb87ddab Mon Sep 17 00:00:00 2001
Message-ID: 
In-Reply-To: 
References: 
From: Ihor Radchenko 
Date: Tue, 26 Dec 2023 15:15:23 +0100
Subject: [PATCH v4 2/5] doc/org-manual.org: Describe export flow

* doc/org-manual.org (Summary of the export process): Explain how the
export process is handled in Org mode.
---
 doc/org-manual.org | 148 +
 1 file changed, 148 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 377706ee7..66a582eae 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16505,6 +16505,154 @@ *** Defining filters for individual files
 ,#+END_SRC
 #+end_example
 
+*** Summary of the export process
+:PROPERTIES:
+:UNNUMBERED: notoc
+:END:
+
+Org mode export is a multi-step process that works on a temporary copy
+of the buffer.  The export process consists of 4 major steps:
+
+1. Process the temporary copy, making necessary changes to the buffer
+   text;
+
+2. Parse the buffer, converting plain Org markup into an abstract
+   syntax tree (AST);
+
+3. Convert the AST to text, as prescribed by the selected export
+   backend;
+
+4. Post-process the resulting exported text.
+
+
+#+texinfo: @noindent
+Process temporary copy of the source Org buffer [fn::Unless
+otherwise specified, each step of the export process only operates on
+the accessible portion of the buffer.  When subtree export is selected
+(see [[*The Export Dispatcher]]), the buffer is narrowed to the body of
+the selected subtree, so that the rest of the buffer text, except
+export keywords, does not contribute to the export output.]:
+
+1. Execute ~org-export-before-processing-functions~ (see [[*Export hooks]]);
+
+2. Expand =#+include= keywords in the whole buffer (see
+   [[*Include Files]]);
+
+3. Remove commented subtrees in the whole buffer (see [[*Comment
+   Lines]]);
+
+4. Replace macros in the whole buffer (see [[*Macro Replacement]]);
+
+5. When ~org-export-use-babel~ is non-nil (default), process code
+   blocks:
+
+   - Leave code blocks inside archived subtrees (see [[*Internal
+ archiving]]) as is;
+
+   - Evaluate all the other code blocks according to code block
+ headers (see [[*Limit code block evaluation]]);
+
+   - Remove code, results of evaluation, both, or neither according
+ to =:exports= header argument (see [[*Exporting Code Blocks]]).
+
+
+#+texinfo: @noindent
+Parse the temporary buffer, creating AST:
+
+1. Execute ~org-export-before-parsing-functions~ (see [[*Export hooks]]).
+   The hook functions may still modify the buffer;
+
+2. Calculate export option values according to subtree-specific export
+   settings, in-buffer keywords, =#+BIND= keywords, and buffer-local
+   and global