bug#53316: 28.0.91; Missing Transient manual in Emacs

[Eli Zaretskii]

On February 21, 2022 6:34:39 AM GMT+02:00, Richard Stallman <rms@gnu.org> wrote:
> 
>   > The original sources for this manual are in Org, but the program that
>   > produces Texinfo from the Org original has problems that need to be
>   > resolved before we can include the Org sources in the Emacs release
>   > tarball.  The Org sources themselves also have several issues.
> 
> Thanks.  Now I understand the problem.
> 
>   > The current Texinfo sources in the repository were heavily edited to
>   > solve many problems in the original version converted from Org to
>   > Texinfo, and that is how we intend to distribute that in Emacs 28.1.
> 
> That's not a solution.

It is IMNSHO a sufficient stopgap while we are working on a better solution.  
It actually coincides with one of the alternatives for our course of action 
that you describe below.

> We must not do that.  What could we do instead?
> 
> We could distribute this package without its manual.  That would be a
> practical problem, but not a disaster.  It is a reasonable option.
> But we have other options too.  Here are some ideas.
> 
> * Delete Transient from the Emacs 28 release.  People can get it from
>   the separately released Org mode.

Transient is not just a manual, Transient is an Emacs Lisp package, which is 
used in Emacs.  Removing its manual is only acceptable to me if we also remove 
the package and all its uses.  That sounds drastic and unnecessary.

> * Fork the manual, making a version for which the Texinfo form is the
>   real source that we edit.  That version can be included in Emacs 28.
>   This forkage would be a practical problem, but not a disaster.

This is what we did, in effect.  The Texinfo sources were heavily edited, and 
diverged significantly from the results of conversion from Org.

> * Write a converter to generate that manual's Org-format source from
>   the Texinfo form.  Then the Texinfo form will be the real source
>   code, and we can include it both in Emacs and in the Org release.
>   This way, there will be no practical problem, only the inconvenience
>   of editing that manual in Texinfo rather than some other source
>   format.

The converter exists, but has problems that need to be resolved before the 
results could be acceptable.  We hope this will be done in the future, and will 
allow us to use the Org sources instead of Texinfo.

> I suspect that automatically converting Org format to Texinfo format
> gives bad Texinfo output.  Texinfo has many different markup
> constructs to make visual distinctions in the text.  Consider @samp,
> @code, @kbd, @dfn, @emph, @var. @file, @url, and more.
> 
> How does Org format express those distinctions?  I fear the answer
> is, "It doesn't."  I would be glad to find that that problem
> has been fixed.

Fof future releases, we indeed hope to see the problems of conversion from Org 
resolved, and then we can switch to distributing the Org sources instead of 
Texinfo.