Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Robert Pluim]

>>>>> On Thu,  6 Jun 2024 08:36:16 -0400 (EDT), Eli Zaretskii <eliz@gnu.org> said:

    Eli> diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in
    Eli> index 2841916dc89..b26d3525a22 100644
    Eli> --- a/doc/misc/Makefile.in
    Eli> +++ b/doc/misc/Makefile.in
    Eli> @@ -250,6 +250,7 @@ define org_template
    Eli>   $(1:.org=.texi): $(1) ${top_srcdir}/lisp/org/ox-texinfo.el
    Eli>  	$${AM_V_GEN}cd "$${srcdir}" && $${emacs} -l ox-texinfo \
    Eli>  	  --eval '(setq gc-cons-threshold 50000000)' \
    Eli> +	  --eval '(setq org-confirm-babel-evaluate nil)' \
    Eli>  	  -f org-texinfo-export-to-texinfo-batch $$(notdir $$<) $$(notdir $$@)
    Eli>  endef

This has set off my paranoia alarm. So anyone that manages to
sneak malicious emacs lisp code into the org manual gets to run that
code on the machines of everyone who builds emacs from source?

(I know, I know, we already run emacs lisp code during the build. But
it comes from .el files, generally, not documentation).

Robert
-- 

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Kyle Meyer]

Robert Pluim writes:

> This has set off my paranoia alarm. So anyone that manages to
> sneak malicious emacs lisp code into the org manual gets to run that
> code on the machines of everyone who builds emacs from source?

Yes.

> (I know, I know, we already run emacs lisp code during the build. But
> it comes from .el files, generally, not documentation).

I understand.

As mentioned by Ihor (+cc) in bug#71394, this change is needed before
syncing the latest Org release to the Emacs tree due to Org's 715148131
(org-manual: Automatically generate export option list, 2023-07-31).

That's not an argument that the Emacs side should accept this change.
But if not, we'll need to adjust things on Org's end.

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Po Lu]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Thu,  6 Jun 2024 08:36:16 -0400 (EDT), Eli Zaretskii <eliz@gnu.org> said:
>
>     Eli> diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in
>     Eli> index 2841916dc89..b26d3525a22 100644
>     Eli> --- a/doc/misc/Makefile.in
>     Eli> +++ b/doc/misc/Makefile.in
>     Eli> @@ -250,6 +250,7 @@ define org_template
>     Eli>   $(1:.org=.texi): $(1) ${top_srcdir}/lisp/org/ox-texinfo.el
>     Eli>  	$${AM_V_GEN}cd "$${srcdir}" && $${emacs} -l ox-texinfo \
>     Eli>  	  --eval '(setq gc-cons-threshold 50000000)' \
>     Eli> +	  --eval '(setq org-confirm-babel-evaluate nil)' \
>     Eli>  	  -f org-texinfo-export-to-texinfo-batch $$(notdir $$<) $$(notdir $$@)
>     Eli>  endef
>
> This has set off my paranoia alarm. So anyone that manages to
> sneak malicious emacs lisp code into the org manual gets to run that
> code on the machines of everyone who builds emacs from source?

No doubt you meant that anyone who manages to sneak malicious code into
Emacs gets to run that code on the machines of everyone who builds Emacs
from source, which is stating the obvious...

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[tomas]

[-- Attachment #1: Type: text/plain, Size: 1773 bytes --]

On Fri, Jun 07, 2024 at 11:54:55AM +0800, Po Lu wrote:
> Robert Pluim <rpluim@gmail.com> writes:
> 
> >>>>>> On Thu,  6 Jun 2024 08:36:16 -0400 (EDT), Eli Zaretskii <eliz@gnu.org> said:
> >
> >     Eli> diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in
> >     Eli> index 2841916dc89..b26d3525a22 100644
> >     Eli> --- a/doc/misc/Makefile.in
> >     Eli> +++ b/doc/misc/Makefile.in
> >     Eli> @@ -250,6 +250,7 @@ define org_template
> >     Eli>   $(1:.org=.texi): $(1) ${top_srcdir}/lisp/org/ox-texinfo.el
> >     Eli>  	$${AM_V_GEN}cd "$${srcdir}" && $${emacs} -l ox-texinfo \
> >     Eli>  	  --eval '(setq gc-cons-threshold 50000000)' \
> >     Eli> +	  --eval '(setq org-confirm-babel-evaluate nil)' \
> >     Eli>  	  -f org-texinfo-export-to-texinfo-batch $$(notdir $$<) $$(notdir $$@)
> >     Eli>  endef
> >
> > This has set off my paranoia alarm. So anyone that manages to
> > sneak malicious emacs lisp code into the org manual gets to run that
> > code on the machines of everyone who builds emacs from source?
> 
> No doubt you meant that anyone who manages to sneak malicious code into
> Emacs gets to run that code on the machines of everyone who builds Emacs
> from source, which is stating the obvious...

This is, strictly speaking, right, of course. Expectation-wise it does
lower the bar for an attacker somewhat, since now the malicious code just
has to be snuck into documentation.

So I think Robert is right that it's worth a discussion (whatever the
outcome might be: perhaps treat the doc as code and give it as much
scrutiny?

Anyway, the libxz episode shows that it seems to be easier to sneak
malicious code "elsewhere" (in that case it was the test suite, but
you get te idea).

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Po Lu]

<tomas@tuxteam.de> writes:

> This is, strictly speaking, right, of course. Expectation-wise it does
> lower the bar for an attacker somewhat, since now the malicious code
> just has to be snuck into documentation.

This can only be true if documentation changes are scrutinized so little
that code, and by extension malicious code simply passes unnoticed.
Otherwise, it would be best to credit the Org Mode developers with the
same due dilligence as ours, or the resulting attitude will appear
condescending at best.

> So I think Robert is right that it's worth a discussion (whatever the
> outcome might be: perhaps treat the doc as code and give it as much
> scrutiny?
>
> Anyway, the libxz episode shows that it seems to be easier to sneak
> malicious code "elsewhere" (in that case it was the test suite, but
> you get te idea).

You mean to imply that Org Mode is more susceptible to organized
sabotage than other players whose code we import, such as Gnulib, or,
heaven forbid, we ourselves?  That way lies madness.

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[tomas]

[-- Attachment #1: Type: text/plain, Size: 701 bytes --]

On Fri, Jun 07, 2024 at 01:13:56PM +0800, Po Lu wrote:
> <tomas@tuxteam.de> writes:

[...]

> This can only be true if documentation changes are scrutinized so little
> that code, and by extension malicious code simply passes unnoticed.

[...]

> You mean to imply that Org Mode is more susceptible to organized
> sabotage than other players whose code we import, such as Gnulib, or,
> heaven forbid, we ourselves?  That way lies madness.

Not at all. I was just supporting Robert's idea of having this discussion.
I don't thing he (or anyone) would propose to rule out executing "generic"
code in document generation. Just that doing this implies higher awareness.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Eli Zaretskii]

> Date: Fri, 7 Jun 2024 06:26:10 +0200
> Cc: Robert Pluim <rpluim@gmail.com>, emacs-devel@gnu.org,
>  Kyle Meyer <kyle@kyleam.com>
> From: <tomas@tuxteam.de>
> 
> > >     Eli> diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in
> > >     Eli> index 2841916dc89..b26d3525a22 100644
> > >     Eli> --- a/doc/misc/Makefile.in
> > >     Eli> +++ b/doc/misc/Makefile.in
> > >     Eli> @@ -250,6 +250,7 @@ define org_template
> > >     Eli>   $(1:.org=.texi): $(1) ${top_srcdir}/lisp/org/ox-texinfo.el
> > >     Eli>  	$${AM_V_GEN}cd "$${srcdir}" && $${emacs} -l ox-texinfo \
> > >     Eli>  	  --eval '(setq gc-cons-threshold 50000000)' \
> > >     Eli> +	  --eval '(setq org-confirm-babel-evaluate nil)' \
> > >     Eli>  	  -f org-texinfo-export-to-texinfo-batch $$(notdir $$<) $$(notdir $$@)
> > >     Eli>  endef
> > >
> > > This has set off my paranoia alarm. So anyone that manages to
> > > sneak malicious emacs lisp code into the org manual gets to run that
> > > code on the machines of everyone who builds emacs from source?
> > 
> > No doubt you meant that anyone who manages to sneak malicious code into
> > Emacs gets to run that code on the machines of everyone who builds Emacs
> > from source, which is stating the obvious...
> 
> This is, strictly speaking, right, of course. Expectation-wise it does
> lower the bar for an attacker somewhat, since now the malicious code just
> has to be snuck into documentation.
> 
> So I think Robert is right that it's worth a discussion (whatever the
> outcome might be: perhaps treat the doc as code and give it as much
> scrutiny?

That ship sailed when we decided to allow manuals to be written in
Org.  So discussing this now is way too late, unless you want to
suggest to go back on that decision and force all the manuals to be
written in Texinfo.

> Anyway, the libxz episode shows that it seems to be easier to sneak
> malicious code "elsewhere" (in that case it was the test suite, but
> you get te idea).

So you are saying that our co-maintainers are not to be trusted not to
sneak such code into release tarballs?  That's quite an insult, I'd
say.

Why is it that a crime perpetrated by some villain immediately causes
people to suspect everyone around them to be capable of similar
crimes?

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Robert Pluim]

>>>>> On Fri, 07 Jun 2024 09:42:18 +0300, Eli Zaretskii <eliz@gnu.org> said:
    >> This is, strictly speaking, right, of course. Expectation-wise it does
    >> lower the bar for an attacker somewhat, since now the malicious code just
    >> has to be snuck into documentation.
    >> 
    >> So I think Robert is right that it's worth a discussion (whatever the
    >> outcome might be: perhaps treat the doc as code and give it as much
    >> scrutiny?

    Eli> That ship sailed when we decided to allow manuals to be written in
    Eli> Org.  So discussing this now is way too late, unless you want to
    Eli> suggest to go back on that decision and force all the manuals to be
    Eli> written in Texinfo.

Allowing Org just added another markup language. Subverting that
requires crafting documentation that causes the texinfo or org
handling code to misbehave. I doubt thatʼs impossible, given the
ingenuity of attackers, but enabling direct evaluation of emacs lisp
makes such subversion a whole lot easier.

    >> Anyway, the libxz episode shows that it seems to be easier to sneak
    >> malicious code "elsewhere" (in that case it was the test suite, but
    >> you get te idea).

    Eli> So you are saying that our co-maintainers are not to be trusted not to
    Eli> sneak such code into release tarballs?  That's quite an insult, I'd
    Eli> say.

Itʼs not a question of trust, nor an attack on maintainersʼ ability:
hiding such code from well-intentioned, skilled maintainers can and
has been done.

    Eli> Why is it that a crime perpetrated by some villain immediately causes
    Eli> people to suspect everyone around them to be capable of similar
    Eli> crimes?

Nobody is accusing maintainers of bad intentions. My point was merely
that we should think carefully about enabling such a feature.

If the end result is that documentation changes are inspected more
closely, thatʼs not necessarily a bad thing.

Robert
-- 

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[tomas]

[-- Attachment #1: Type: text/plain, Size: 1611 bytes --]

On Fri, Jun 07, 2024 at 09:42:18AM +0300, Eli Zaretskii wrote:

[...]

> > So I think Robert is right that it's worth a discussion (whatever the
> > outcome might be: perhaps treat the doc as code and give it as much
> > scrutiny?
> 
> That ship sailed when we decided to allow manuals to be written in
> Org.  So discussing this now is way too late, unless you want to
> suggest to go back on that decision and force all the manuals to be
> written in Texinfo.

Please, don't get me wrong: there are many levels there: Org itself tries
to separate "built in" -- meaning you need a bug in Org's implementation
to stage an exploit vs. "execute arbitrary external program with arbitrary
args" -- meaning "anyting goes". This is a useful distinction (heck, even
TeX ca 1979 does that).

> > Anyway, the libxz episode [...]

> So you are saying that our co-maintainers are not to be trusted not to
> sneak such code into release tarballs?  That's quite an insult, I'd
> say.

I think this is the wrong approach. Of course we trust people all the time.
I do trust you all *a lot* whenever I do "sudo make install".

It's more about "taking care of each other". About knowing that yes, such
things do happen and about having a rough idea what to do in such situations.

But at the end of the day, there's no way around trust and life is much
nicer if it's the default.

> Why is it that a crime perpetrated by some villain immediately causes
> people to suspect everyone around them to be capable of similar
> crimes?

That's not the way I choose to live, no.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Stefan Kangas]

Kyle Meyer <kyle@kyleam.com> writes:

> As mentioned by Ihor (+cc) in bug#71394, this change is needed before
> syncing the latest Org release to the Emacs tree due to Org's 715148131
> (org-manual: Automatically generate export option list, 2023-07-31).

Does it really need to generated automatically on every build, or can it
be handled in some other way?  For example, we pre-generate our loaddefs
files and commit the result.

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: <tomas@tuxteam.de>,  luangruo@yahoo.com,  emacs-devel@gnu.org,
>   kyle@kyleam.com
> Date: Fri, 07 Jun 2024 09:38:12 +0200
> 
>     >> So I think Robert is right that it's worth a discussion (whatever the
>     >> outcome might be: perhaps treat the doc as code and give it as much
>     >> scrutiny?
> 
>     Eli> That ship sailed when we decided to allow manuals to be written in
>     Eli> Org.  So discussing this now is way too late, unless you want to
>     Eli> suggest to go back on that decision and force all the manuals to be
>     Eli> written in Texinfo.
> 
> Allowing Org just added another markup language.

It also introduced the fact that we run Lisp to produce documentation.

> Subverting that
> requires crafting documentation that causes the texinfo or org
> handling code to misbehave. I doubt thatʼs impossible, given the
> ingenuity of attackers, but enabling direct evaluation of emacs lisp
> makes such subversion a whole lot easier.

Adding that single setq on the command line means "direct evaluation
of Emacs Lisp", whereas running Org code (in Emacs Lisp!) to produce
the manuals does not?  What am I missing here?

>     >> Anyway, the libxz episode shows that it seems to be easier to sneak
>     >> malicious code "elsewhere" (in that case it was the test suite, but
>     >> you get te idea).
> 
>     Eli> So you are saying that our co-maintainers are not to be trusted not to
>     Eli> sneak such code into release tarballs?  That's quite an insult, I'd
>     Eli> say.
> 
> Itʼs not a question of trust, nor an attack on maintainersʼ ability:
> hiding such code from well-intentioned, skilled maintainers can and
> has been done.

So you are saying that we don't understand code that we review and
approve for installing?

>     Eli> Why is it that a crime perpetrated by some villain immediately causes
>     Eli> people to suspect everyone around them to be capable of similar
>     Eli> crimes?
> 
> Nobody is accusing maintainers of bad intentions.

That's not the only interpretation of what's been said.  The reference
to xz already speaks volumes about the attitude.

> My point was merely
> that we should think carefully about enabling such a feature.

And you think I haven't when I installed the change?  Why would you
think that?

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> It also introduced the fact that we run Lisp to produce documentation.
>
>> Subverting that
>> requires crafting documentation that causes the texinfo or org
>> handling code to misbehave. I doubt thatʼs impossible, given the
>> ingenuity of attackers, but enabling direct evaluation of emacs lisp
>> makes such subversion a whole lot easier.
>
> Adding that single setq on the command line means "direct evaluation
> of Emacs Lisp", whereas running Org code (in Emacs Lisp!) to produce
> the manuals does not?  What am I missing here?
>
>>     >> Anyway, the libxz episode shows that it seems to be easier to sneak
>>     >> malicious code "elsewhere" (in that case it was the test suite, but
>>     >> you get te idea).
>> 
>>     Eli> So you are saying that our co-maintainers are not to be trusted not to
>>     Eli> sneak such code into release tarballs?  That's quite an insult, I'd
>>     Eli> say.
>> 
>> Itʼs not a question of trust, nor an attack on maintainersʼ ability:
>> hiding such code from well-intentioned, skilled maintainers can and
>> has been done.
>
> So you are saying that we don't understand code that we review and
> approve for installing?
>
>>     Eli> Why is it that a crime perpetrated by some villain immediately causes
>>     Eli> people to suspect everyone around them to be capable of similar
>>     Eli> crimes?
>> 
>> Nobody is accusing maintainers of bad intentions.
>
> That's not the only interpretation of what's been said.  The reference
> to xz already speaks volumes about the attitude.
>
>> My point was merely
>> that we should think carefully about enabling such a feature.
>
> And you think I haven't when I installed the change?  Why would you
> think that?

100% agreement.

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > This has set off my paranoia alarm. So anyone that manages to
  > sneak malicious emacs lisp code into the org manual gets to run that
  > code on the machines of everyone who builds emacs from source?

I think this is a significant drawback.

Are there other reasonable solutions to the current problem, which
would avoid this drawback?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Ihor Radchenko]

Stefan Kangas <stefankangas@gmail.com> writes:

> Kyle Meyer <kyle@kyleam.com> writes:
>
>> As mentioned by Ihor (+cc) in bug#71394, this change is needed before
>> syncing the latest Org release to the Emacs tree due to Org's 715148131
>> (org-manual: Automatically generate export option list, 2023-07-31).
>
> Does it really need to generated automatically on every build, or can it
> be handled in some other way?  For example, we pre-generate our loaddefs
> files and commit the result.

Preferably, every build, I think.

What we do in Org mode manual is examining an Elisp variable and build a
table summarizing its values. If that variable changes in the code, the
manual should reflect this change.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Ihor Radchenko]

To Eli,

AFAIU, emacs-30 branch will be cut next week.  This discussion is what
is holding us from merging the released Org 9.7 , which we would like to
see in Emacs 30.

Should we wait until this discussion settles before we merge?

Robert Pluim <rpluim@gmail.com> writes:

> This has set off my paranoia alarm. So anyone that manages to
> sneak malicious emacs lisp code into the org manual gets to run that
> code on the machines of everyone who builds emacs from source?
>
> (I know, I know, we already run emacs lisp code during the build. But
> it comes from .el files, generally, not documentation).

Strictly speaking, pure TeX code (which can be placed directly inside
TexInfo manuals) is also executed when generating documentation. At the
end, TeX is a complete programming language.  And there are ways to
exploit it.

In any case, there is a reason we want to enable generated content in
the manuals. We do not do it just for fun.

The installed change allows generating parts of the manual directly from
the Elisp values defined in Org mode .el files. This greatly reduces
maintenance burden for certain parts of the code that must be updated
every single time we add a new option.

IMHO, the potential increased chance of malicious code slipping through
the review process is greatly outweighed by the decreased maintenance of
that (and potentially other) part(s) of the Org manual.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Stefan Kangas]

Ihor Radchenko <yantar92@posteo.net> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Kyle Meyer <kyle@kyleam.com> writes:
>>
>>> As mentioned by Ihor (+cc) in bug#71394, this change is needed before
>>> syncing the latest Org release to the Emacs tree due to Org's 715148131
>>> (org-manual: Automatically generate export option list, 2023-07-31).
>>
>> Does it really need to generated automatically on every build, or can it
>> be handled in some other way?  For example, we pre-generate our loaddefs
>> files and commit the result.
>
> Preferably, every build, I think.
>
> What we do in Org mode manual is examining an Elisp variable and build a
> table summarizing its values. If that variable changes in the code, the
> manual should reflect this change.

Right, but the same is true for our loaddefs files (you want them
up-to-date, or you get warnings, etc.), and even for them it's been
enough to have a cronjob regenerate and commit them once per month.

So I think my question still stands.

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: emacs-devel@gnu.org, Kyle Meyer <kyle@kyleam.com>
> Date: Sun, 09 Jun 2024 18:12:39 +0000
> 
> To Eli,
> 
> AFAIU, emacs-30 branch will be cut next week.  This discussion is what
> is holding us from merging the released Org 9.7 , which we would like to
> see in Emacs 30.
> 
> Should we wait until this discussion settles before we merge?

From where I stand, you can merge it ASAP.  In fact, I'd like to urge
you to merge sooner rather than later, since this is one of the
changes for which I'm waiting before branching.

Thanks.

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Ihor Radchenko]

Stefan Kangas <stefankangas@gmail.com> writes:

>>> Does it really need to generated automatically on every build, or can it
>>> be handled in some other way?  For example, we pre-generate our loaddefs
>>> files and commit the result.
>>
>> Preferably, every build, I think.
>>
>> What we do in Org mode manual is examining an Elisp variable and build a
>> table summarizing its values. If that variable changes in the code, the
>> manual should reflect this change.
>
> Right, but the same is true for our loaddefs files (you want them
> up-to-date, or you get warnings, etc.), and even for them it's been
> enough to have a cronjob regenerate and commit them once per month.
>
> So I think my question still stands.

It is certainly possible. We would need to run pre-processing and then
generate the final manuals from yet another intermediate pre-processed
.org file. However, I am not sure why would we need to bother with such
extra work. What would be the benefit?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Stefan Kangas]

Ihor Radchenko <yantar92@posteo.net> writes:

> It is certainly possible. We would need to run pre-processing and then
> generate the final manuals from yet another intermediate pre-processed
> .org file. However, I am not sure why would we need to bother with such
> extra work. What would be the benefit?

I don't consider this urgent or a blocker for merging the latest Org
mode release, but the benefit would be to avoid running code from a
documentation file on every build.

You can, of course, slip in malicious changes anywhere, but it's
arguably easier in a documentation file since some of us might relax and
think that it's safer since it's "just documentation".

Consider, for example, sweeping changes like fixing typos, or
reformatting.  Now we need to look at such things more closely also when
it only concerns documentation fixes.

To be clear, all of us are obviously doing the best job we can, and some
of us are doing a very fine job indeed, but bugs still can and do slip
under our radar.  There's nothing unique about malicious code that means
that it's somehow impossible for us to miss it.

IOW, I don't think I see why we shouldn't try to make our job easier if
we can.  Hence my question how hard it would be to replicate what we
already do for loaddefs files.  If it's not practical, then so be it.

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Ihor Radchenko]

Stefan Kangas <stefankangas@gmail.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> It is certainly possible. We would need to run pre-processing and then
>> generate the final manuals from yet another intermediate pre-processed
>> .org file. However, I am not sure why would we need to bother with such
>> extra work. What would be the benefit?
>
> ...
> IOW, I don't think I see why we shouldn't try to make our job easier if
> we can.  Hence my question how hard it would be to replicate what we
> already do for loaddefs files.  If it's not practical, then so be it.

May you please point me to where in the Makefiles you do the
pre-generation you are referring to?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Stefan Kangas]

Ihor Radchenko <yantar92@posteo.net> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Ihor Radchenko <yantar92@posteo.net> writes:
>>
>>> It is certainly possible. We would need to run pre-processing and then
>>> generate the final manuals from yet another intermediate pre-processed
>>> .org file. However, I am not sure why would we need to bother with such
>>> extra work. What would be the benefit?
>>
>> ...
>> IOW, I don't think I see why we shouldn't try to make our job easier if
>> we can.  Hence my question how hard it would be to replicate what we
>> already do for loaddefs files.  If it's not practical, then so be it.
>
> May you please point me to where in the Makefiles you do the
> pre-generation you are referring to?

Running the `admin/update_autogen` script results in commits like this
one:

    commit 1ea3b369021c90701c634c512426f75ce1291d77
    Author: Eli Zaretskii <eliz@gnu.org>
    Date:   Sat Mar 9 04:24:30 2024 -0500

        Auto-commit of loaddefs files.

Glenn used to run that from crontab for years, then I did it for a
while, and now we run it manually every so often.  (It's on my todo list
to get a cronjob back up and running, but I didn't get around to it yet
for uninteresting reasons.)

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Ihor Radchenko]

Stefan Kangas <stefankangas@gmail.com> writes:

>> May you please point me to where in the Makefiles you do the
>> pre-generation you are referring to?
>
> Running the `admin/update_autogen` script results in commits like this
> one:
>
>     commit 1ea3b369021c90701c634c512426f75ce1291d77
>     Author: Eli Zaretskii <eliz@gnu.org>
>     Date:   Sat Mar 9 04:24:30 2024 -0500
>
>         Auto-commit of loaddefs files.

Thanks!
I am now looking into that script, and into doc/misc/Makefile.
I can see two approaches wrt to the Makefile:

1. Implement a separate Makefile target to generate org.org version with
   all the necessary code blocks inside evaluated, so that there is no
   need to redo it during make doc.

2. (simpler) Just reuse the existing .org->.texi target and run the full
   .texi generation from admin/update_autogen script itself.

The second option is less work and also ultimately shorter build times
as there will be no need to arrange Org mode compilation, and
.org->.texi conversion.

What do you think about such approach?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: master c86995d07e9: Enable code block evaluation when generating .org manuals

[Stefan Kangas]

Ihor Radchenko <yantar92@posteo.net> writes:

>> Running the `admin/update_autogen` script results in commits like this
>> one:
>>
>>     commit 1ea3b369021c90701c634c512426f75ce1291d77
>>     Author: Eli Zaretskii <eliz@gnu.org>
>>     Date:   Sat Mar 9 04:24:30 2024 -0500
>>
>>         Auto-commit of loaddefs files.
>
> Thanks!
> I am now looking into that script, and into doc/misc/Makefile.
> I can see two approaches wrt to the Makefile:
>
> 1. Implement a separate Makefile target to generate org.org version with
>    all the necessary code blocks inside evaluated, so that there is no
>    need to redo it during make doc.
>
> 2. (simpler) Just reuse the existing .org->.texi target and run the full
>    .texi generation from admin/update_autogen script itself.
>
> The second option is less work and also ultimately shorter build times
> as there will be no need to arrange Org mode compilation, and
> .org->.texi conversion.
>
> What do you think about such approach?

I think either approach is acceptable, so whichever you prefer is fine.
There is always some drawback to checking in generated files though, so
let's see if anyone else has any comments or better ideas first.

That said, I think we should let `admin/update_autogen` be strictly
about loaddefs files.  If we decide to go in this direction, we could
add a new script `admin/update-manuals`.  If it needs to share code with
the former, the shared code could go in `admin/emacs-shell-lib`.