From: Matt <matt@excalamus.com>
To: "Ihor Radchenko" <yantar92@posteo.net>
Cc: "emacs-orgmode" <emacs-orgmode@gnu.org>
Subject: Re: [PATCH v3] org-manual: Describe export process flow
Date: Wed, 27 Dec 2023 19:02:18 +0100 [thread overview]
Message-ID: <18cac710817.e615cdf1468737.687007161508493949@excalamus.com> (raw)
In-Reply-To: <87frznefpn.fsf@localhost>
---- 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
next prev parent reply other threads:[~2023-12-27 18:10 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
2023-12-27 17:08 ` [PATCH v3] " Ihor Radchenko
2023-12-27 18:02 ` Matt [this message]
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=18cac710817.e615cdf1468737.687007161508493949@excalamus.com \
--to=matt@excalamus.com \
--cc=emacs-orgmode@gnu.org \
--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).