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

[Matt]

 ---- On Wed, 27 Dec 2023 18:05:05 +0100  Ihor Radchenko  wrote --- 
 
 > Matt matt@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