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

2023-12-27 Thread Matt 


  On Wed, 27 Dec 2023 18:05:05 +0100  Ihor Radchenko  wrote --- 
 
 > Matt m...@excalamus.com> writes:
 > > 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
 > >  some-kind-of-reference-to-the-new-manual-section
 > > "
 > 
 > AFAIU, you are asking to add it to WORG page. However, it is too early.
 > The online Org manual that we can link to is only for stable Org
 > version. So, only after the next release.

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

The new manual section is unique in that it gives detailed steps about
the order of execution.  Without knowing the code (so I may be
mistaken), it seems like a risk that the ox.el code and manual could
get out of sync.  This is why I wouldn't suggest documenting the
execution order for something like source blocks.  However, since
end-users have a lot of flexiblity in customizing the export process,
it's helpful for them to understand it.  It makes sense to add the new
manual section.

Mentioning the new manual section in the ox.el commentary would help
someone new to the ox.el code.  It may also help keep the new manual
section and ox.el aligned (should anything in the execution
order/process change in ox.el) by reminding someone changing the code
that there's a manual section specifically about *how* the code works.

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

2023-12-27 Thread Ihor Radchenko 
Matt  writes:

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

Of course. Any patch posted on the mailing list is open to feedback.
Especially mine, since I can push it directly if I think that the patch
is in a good shape.

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

Thanks for proofreading!
I accepted all but one suggestion on grammar.
The new iteration of the patch is attached.

>  >- 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]]);"

Here, "export keywords" and "export options" are two different groups. I
wanted to indicate this and went with ";":

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

> Checking ox.el, I see that the commentary says,
>
> ";; See  for
> ;; more information."
>
> Maybe also let maintainers know about this manual section:
>
> "See:
> 
> "

AFAIU, you are asking to add it to WORG page. However, it is too early.
The online Org manual that we can link to is only for stable Org
version. So, only after the next release.

For now, I added a link to the WORG page to "Extending an existing
backend" section. It should be a good reference for people writing
non-trivial derived backends.

>From 6f6a1a190724176da7373e3d25f9df0bf60dbac9 Mon Sep 17 00:00:00 2001
Message-ID: <6f6a1a190724176da7373e3d25f9df0bf60dbac9.1703696392.git.yanta...@posteo.net>
From: Ihor Radchenko 
Date: Wed, 27 Dec 2023 14:23:29 +0100
Subject: [PATCH v3 1/3] 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 786e3e78d4c6846188477452a529132aba76149f Mon Sep 17 00:00:00 2001
Message-ID: <786e3e78d4c6846188477452a529132aba76149f.1703696392.git.yanta...@posteo.net>
In-Reply-To: <6f6a1a190724176da7373e3d25f9df0bf60dbac9.1703696392.git.yanta...@posteo.net>
References: <6f6a1a190724176da7373e3d25f9df0bf60dbac9.1703696392.git.yanta...@posteo.net>
From: Ihor Radchenko 
Date: Tue, 26 Dec 2023 15:15:23 +0100
Subject: [PATCH v3 2/3] 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