Transient manual

Transient manual

[Po Lu]

The recently imported Transient manual fails to compile as part of
Emacs, because it relies on features absent from Texinfo 4.13.  For
example, it presumes that Makeinfo is capable of extrapolating the Up
fields of each node on the basis of an implicitly generated menu.

There are some other difficulties I spotted, such as the use of Unicode
quotes rather than `` and '', and so on.

I will fix these issues on master, but would the Transient developers
take care to avoid these pitfalls in the future?  There are several
machines I use for Emacs development where anything newer than Texinfo
4.13 is unobtanium, consequent of difficulties with their Perl
installations.

Re: Transient manual

[Jonas Bernoulli]

Po Lu <luangruo@yahoo.com> writes:

> The recently imported Transient manual fails to compile as part of
> Emacs, because it relies on features absent from Texinfo 4.13.  For
> example, it presumes that Makeinfo is capable of extrapolating the Up
> fields of each node on the basis of an implicitly generated menu.

Some time ago I also noticed that exporting from org to texi suddenly
stopped generating certain menus.  I looked at the history of org and
ox-texinfo.el in particular, but could not find a code change that would
explain that change in behavior.  I resorted to manually discarding the
removal of these menus whenever I regenerated the manual, planning to
eventually investigate further.  I never got around to it and apparently
I wasn't paying attention one time and committed the removal of the
menus.

> There are some other difficulties I spotted, such as the use of Unicode
> quotes rather than `` and '', and so on.

I've changed the org to texi transformation to use ``...''.

> I will fix these issues on master, but would the Transient developers
> take care to avoid these pitfalls in the future?  There are several
> machines I use for Emacs development where anything newer than Texinfo
> 4.13 is unobtanium, consequent of difficulties with their Perl
> installations.

I tried but failed.  I'll ask the org developers for help to avoid that
in the future.

(Texinfo 4.13 is very old.  It was released on 2008-09-18.  The current
release is 7.0.3.  I don't know how much longer we should support such
an ancient version because some machines are stuck on a release from 15
years ago.)

Re: Transient manual

[Po Lu]

Jonas Bernoulli <jonas@bernoul.li> writes:

> (Texinfo 4.13 is very old.  It was released on 2008-09-18.  The
> current release is 7.0.3.  I don't know how much longer we should
> support such an ancient version because some machines are stuck on a
> release from 15 years ago.)

Texinfo 4.13 is also the final version of Texinfo written in C; it is
several orders of magnitude faster than anything newer.  I'd prefer we
continue supporting it until doing so really becomes impossible.

TIA.

Re: Transient manual

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

  > I will fix these issues on master, but would the Transient developers
  > take care to avoid these pitfalls in the future?

Can you give them specific suggestion for how to check for these
problems?  Some tests?  A function to search for Unicode quotes and
anything else that should not appear?  Things like that would help
them get it right.


-- 
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: Transient manual

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: emacs-devel@gnu.org
> Date: Wed, 30 Aug 2023 09:08:17 +0800
> 
> Texinfo 4.13 is also the final version of Texinfo written in C; it is
> several orders of magnitude faster than anything newer.

Correction: it's only one order of magnitude faster than 7.x.

Re: Transient manual

[Ihor Radchenko]

Jonas Bernoulli <jonas@bernoul.li> writes:

> Po Lu <luangruo@yahoo.com> writes:
>
>> The recently imported Transient manual fails to compile as part of
>> Emacs, because it relies on features absent from Texinfo 4.13.  For
>> example, it presumes that Makeinfo is capable of extrapolating the Up
>> fields of each node on the basis of an implicitly generated menu.
>
> Some time ago I also noticed that exporting from org to texi suddenly
> stopped generating certain menus.  I looked at the history of org and
> ox-texinfo.el in particular, but could not find a code change that would
> explain that change in behavior.  I resorted to manually discarding the
> removal of these menus whenever I regenerated the manual, planning to
> eventually investigate further.  I never got around to it and apparently
> I wasn't paying attention one time and committed the removal of the
> menus.

It would help if we had a small example demonstrating the problem, Org
output, and desired output.

AFAIK, ox-texinfo file itself is younger than the Texinfo version in
question.

-- 
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: Transient manual

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

  > Texinfo 4.13 is also the final version of Texinfo written in C; it is
  > several orders of magnitude faster than anything newer.

Could you give us an real example of the time difference between the
versions, on a real input job?  That would help us understand the
impact of this issue.


-- 
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: Transient manual

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: jonas@bernoul.li, emacs-devel@gnu.org
> Date: Thu, 31 Aug 2023 21:15:36 -0400
> 
>   > Texinfo 4.13 is also the final version of Texinfo written in C; it is
>   > several orders of magnitude faster than anything newer.
> 
> Could you give us an real example of the time difference between the
> versions, on a real input job?  That would help us understand the
> impact of this issue.

Current version of makeinfo is about 10 times slower than the one from
Texinfo 4.13 if Perl extensions (written in C as part of Texinfo) are
used, and about 15 to 18 times slower if the extensions are not used
(i.e. only Perl code is used for all the Texinfo-to-Info translation).

Of course, current Texinfo has many features that 4.13 didn't support
and many of them simply could not be supported without a complete
redesign and reimplementation of makeinfo as it was originally
designed.  Its one-pass architecture with conversions performed
in-place on the same input buffer simply made some complex features
impossible to implement.  That design is what made it so
lightning-fast, but also put a limit to its extensibility and
development.

Re: Transient manual

[Jonas Bernoulli]

> It would help if we had a small example demonstrating the problem, Org
> output, and desired output.

---- demo.org -------------------------------------------

* only subsections, no direct content
** sub 1
body
** sub 2
body

---- demo.texi with org 9.2.8 ---------------------------

\input texinfo    @c -*- texinfo -*-

[...]

@node only subsections no direct content
@chapter only subsections, no direct content

@menu
* sub 1::
* sub 2::
@end menu

@node sub 1
@section sub 1

body

@node sub 2
@section sub 2

body

@bye

---- demo.texi with org release_9.6.8-743-gaf9c063ed ----

\input texinfo    @c -*- texinfo -*-

[...]

@node only subsections no direct content
@chapter only subsections, no direct content

@node sub 1
@section sub 1

body

@node sub 2
@section sub 2

body

@bye

---------------------------------------------------------

Speaking of af9c063ed, that commit adds another regression and has
to be reverted.

The match-string-no-properties on line 674 needs to access the
match-data from the matching on line 668.  So it is *not* safe to
replace it with other match-data on line 673; the save-match-data
on that line is required.

> AFAIK, ox-texinfo file itself is younger than the Texinfo version in
> question.

Yeah, most likely this issue has nothing to do with the used Texinfo
version.  After all the regression is in code that generates a texi
file from an org file.

Sorry for the delay.

     Cheers,
     Jonas

Re: Transient manual

[Ihor Radchenko]

Jonas Bernoulli <jonas@bernoul.li> writes:

>> It would help if we had a small example demonstrating the problem, Org
>> output, and desired output.
>
> ---- demo.org -------------------------------------------
> ...

Thanks!
I will look into this.

> Speaking of af9c063ed, that commit adds another regression and has
> to be reverted.

Maybe you mean some other commit?
af9c063ed is just changing a docstring.

-- 
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: Transient manual

[Jonas Bernoulli]

Ihor Radchenko <yantar92@posteo.net> writes:

>> Speaking of af9c063ed, that commit adds another regression and has
>> to be reverted.
>
> Maybe you mean some other commit?
> af9c063ed is just changing a docstring.

Yes.  It's e32bd5f7c78c9d92cefd9a78771f9729946fdf73.

Instead of restoring the save-match-data, you could change the order
of the bindings.

When I wrote that function, I decided that I would rather use
save-match-data, even though that could be avoided.  That way the two
bindings which set and then refine CMD based on the first submatch are
next to each other, and only after that has been taken care off, do we
move on to set ARGS based on the second submatch.  But if you think it
is more important to avoid a save-match-data, or think the mistake you
made is likely to be repeated, I am fine with switching up the order.

    Jonas

Re: Transient manual

[Ihor Radchenko]

Jonas Bernoulli <jonas@bernoul.li> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>>> Speaking of af9c063ed, that commit adds another regression and has
>>> to be reverted.
>>
>> Maybe you mean some other commit?
>> af9c063ed is just changing a docstring.
>
> Yes.  It's e32bd5f7c78c9d92cefd9a78771f9729946fdf73.
>
> Instead of restoring the save-match-data, you could change the order
> of the bindings.

Oh. That's from the recent series of refactorings on main...
That's my oversight - I misread the code to be `pcase', not
`pcase-let*'.

> When I wrote that function, I decided that I would rather use
> save-match-data, even though that could be avoided.  That way the two
> bindings which set and then refine CMD based on the first submatch are
> next to each other, and only after that has been taken care off, do we
> move on to set ARGS based on the second submatch.  But if you think it
> is more important to avoid a save-match-data, or think the mistake you
> made is likely to be repeated, I am fine with switching up the order.

It is not super-important. I am just aiming to drop `save-match-data'
where it is not necessary. But I am mostly focusing on
performance-critical code, where is actually matters, reviewing all the
uses along the way.

Fixed, on main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=dbf415b84

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