bug#53316: 28.0.91; Missing Transient manual in Emacs

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Philipp Stephani]

Transient has its own manual (transient.org/.texi), but that's missing
from the version shipped with Emacs.  Could we add the manual to the
Emacs release?


In GNU Emacs 28.0.91 (build 6, x86_64-pc-linux-gnu, GTK+ Version 3.24.30, cairo version 1.16.0)
 of 2022-01-15
Repository revision: 7f36aca99dc1387cfeb599c9f2bb781036f79cf1
Repository branch: emacs-28
Windowing system distributor 'The X.Org Foundation', version 11.0.12013000
System Description: Debian GNU/Linux rodete

Configured using:
 'configure --enable-gcc-warnings=warn-only
 --enable-gtk-deprecation-warnings --without-pop --with-mailutils
 --enable-checking=all --enable-check-lisp-object-type --with-modules
 'CFLAGS=-O0 -ggdb3''

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LIBSELINUX LIBSYSTEMD LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG SECCOMP
SOUND THREADS TIFF TOOLKIT_SCROLL_BARS X11 XDBE XIM XPM GTK3 ZLIB

Important settings:
  value of $LC_TIME: en_DK.utf8
  value of $LANG: en_US.utf8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  indent-tabs-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug sendmail phst skeleton edmacro kmacro
pcase ffap thingatpt url url-proxy url-privacy url-expand url-methods
url-history url-cookie url-domsuf url-util url-parse url-vars mailcap rx
message rmc dired dired-loaddefs rfc822 mml mml-sec epa derived epg
rfc6068 epg-config gnus-util rmail rmail-loaddefs auth-source cl-seq
eieio eieio-core cl-macs eieio-loaddefs password-cache json map
time-date mm-decode mm-bodies mm-encode mail-parse rfc2231 rfc2047
rfc2045 mm-util ietf-drums mail-prsvr mailabbrev mail-utils gmm-utils
mailheader gnutls puny elp dbus xml subr-x seq byte-opt gv bytecomp
byte-compile cconv compile text-property-search comint ansi-color ring
cl-loaddefs cl-lib iso-transl tooltip eldoc paren electric uniquify
ediff-hook vc-hooks lisp-float-type elisp-mode mwheel term/x-win x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe
tabulated-list replace newcomment text-mode lisp-mode prog-mode register
page tab-bar menu-bar rfn-eshadow isearch easymenu timer select
scroll-bar mouse jit-lock font-lock syntax font-core term/tty-colors
frame minibuffer cl-generic cham georgian utf-8-lang misc-lang
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms cp51932
hebrew greek romanian slovak czech european ethiopic indian cyrillic
chinese composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help simple abbrev obarray cl-preloaded nadvice button
loaddefs faces cus-face macroexp files window text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote threads dbusbind inotify
dynamic-setting system-font-setting font-render-setting cairo
move-toolbar gtk x-toolkit x multi-tty make-network-process emacs)

Memory information:
((conses 16 69543 6664)
 (symbols 48 8543 3)
 (strings 32 24824 2518)
 (string-bytes 1 802012)
 (vectors 16 15668)
 (vector-slots 8 207469 16091)
 (floats 8 29 46)
 (intervals 56 228 0)
 (buffers 992 11))

-- 
Google Germany GmbH
Erika-Mann-Straße 33
80636 München

Geschäftsführer: Paul Manicle, Halimah DeLaine Prado
Registergericht und -nummer: Hamburg, HRB 86891
Sitz der Gesellschaft: Hamburg

Diese E-Mail ist vertraulich.  Falls Sie diese fälschlicherweise erhalten haben
sollten, leiten Sie diese bitte nicht an jemand anderes weiter, löschen Sie
alle Kopien und Anhänge davon und lassen Sie mich bitte wissen, dass die E-Mail
an die falsche Person gesendet wurde.

This e-mail is confidential.  If you received this communication by mistake,
please don’t forward it to anyone else, please erase all copies and
attachments, and please let me know that it has gone to the wrong person.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Lars Ingebrigtsen]

Philipp Stephani <p.stephani2@gmail.com> writes:

> Transient has its own manual (transient.org/.texi), but that's missing
> from the version shipped with Emacs.  Could we add the manual to the
> Emacs release?

Sounds like a good idea to me; adding Jonas to the CCs.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Jonas Bernoulli]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Philipp Stephani <p.stephani2@gmail.com> writes:
>
>> Transient has its own manual (transient.org/.texi), but that's missing
>> from the version shipped with Emacs.  Could we add the manual to the
>> Emacs release?
>
> Sounds like a good idea to me; adding Jonas to the CCs.

Agreed.  I was planning to create a new release first and merge that
into "emacs-28" before doing so, but it seems the ship has sailed.

On the other hand it contains important bug fixes (but also new
features) and nothing on "emacs-28" uses it yet.  So maybe it would
still be okay to update even during the pre-release phase; I don't know.
Removing it from "emacs-28" and only releasing it in 29 (or maybe 28.2)
might also be an option.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Philipp Stephani]

> Am 25.01.2022 um 21:30 schrieb Jonas Bernoulli <jonas@bernoul.li>:
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
>> Philipp Stephani <p.stephani2@gmail.com> writes:
>> 
>>> Transient has its own manual (transient.org/.texi), but that's missing
>>> from the version shipped with Emacs.  Could we add the manual to the
>>> Emacs release?
>> 
>> Sounds like a good idea to me; adding Jonas to the CCs.
> 
> Agreed.  I was planning to create a new release first and merge that
> into "emacs-28" before doing so, but it seems the ship has sailed.
> 
> On the other hand it contains important bug fixes (but also new
> features) and nothing on "emacs-28" uses it yet.  So maybe it would
> still be okay to update even during the pre-release phase; I don't know.
> Removing it from "emacs-28" and only releasing it in 29 (or maybe 28.2)
> might also be an option.

Or maybe it would be feasible to add the manual version that corresponds to the Emacs 28 version?

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Jonas Bernoulli]

Philipp Stephani <p.stephani2@gmail.com> writes:

>> Am 25.01.2022 um 21:30 schrieb Jonas Bernoulli <jonas@bernoul.li>:
>> 
>> Lars Ingebrigtsen <larsi@gnus.org> writes:
>> 
>>> Philipp Stephani <p.stephani2@gmail.com> writes:
>>> 
>>>> Transient has its own manual (transient.org/.texi), but that's missing
>>>> from the version shipped with Emacs.  Could we add the manual to the
>>>> Emacs release?
>>> 
>>> Sounds like a good idea to me; adding Jonas to the CCs.
>> 
>> Agreed.  I was planning to create a new release first and merge that
>> into "emacs-28" before doing so, but it seems the ship has sailed.
>> 
>> On the other hand it contains important bug fixes (but also new
>> features) and nothing on "emacs-28" uses it yet.  So maybe it would
>> still be okay to update even during the pre-release phase; I don't know.
>> Removing it from "emacs-28" and only releasing it in 29 (or maybe 28.2)
>> might also be an option.
>
> Or maybe it would be feasible to add the manual version that
> corresponds to the Emacs 28 version?

Yes.  Just saying that wasn't the plan.  (And that won't make the bugs
go away.  And some of them were quite severe, but I believe that those
that made it necessary to kill Emacs from the outside have at least
been neutered, i.e. there's still an error but Emacs remains usable.)

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Michael Albinus]

Jonas Bernoulli <jonas@bernoul.li> writes:

> Agreed.  I was planning to create a new release first and merge that
> into "emacs-28" before doing so, but it seems the ship has sailed.
>
> On the other hand it contains important bug fixes (but also new
> features) and nothing on "emacs-28" uses it yet.  So maybe it would
> still be okay to update even during the pre-release phase; I don't know.
> Removing it from "emacs-28" and only releasing it in 29 (or maybe 28.2)
> might also be an option.

I have a similar problem with Tramp. Emacs 28 pretest has frozen the
files, but changes still arrive. So I trust that people will use the GNU
ELPA version, which is released regularly. In case of reported errors, I
recommend to install it once the error is fixed there.

After the release of Emacs 28.1, these Tramp changes will be merged.

Best regards, Michael.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Jonas Bernoulli]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Philipp Stephani <p.stephani2@gmail.com> writes:
>
>> Transient has its own manual (transient.org/.texi), but that's missing
>> from the version shipped with Emacs.  Could we add the manual to the
>> Emacs release?
>
> Sounds like a good idea to me; adding Jonas to the CCs.

I've just added.

I've added the generated texi file not the org source because to export
that correctly my ox-texinfo+ package is required.  A new implementation
of the main feature of that package recently made it into Org's main
branch, so once the next feature release is merged into Emacs' master
branch, then we can track the org file instead (on master).

     Jonas

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Jonas Bernoulli]

Jonas Bernoulli <jonas@bernoul.li> writes:

> Philipp Stephani <p.stephani2@gmail.com> writes:
>
>>> Am 25.01.2022 um 21:30 schrieb Jonas Bernoulli <jonas@bernoul.li>:
>>> 
>>> Lars Ingebrigtsen <larsi@gnus.org> writes:
>>> 
>>>> Philipp Stephani <p.stephani2@gmail.com> writes:
>>>> 
>>>>> Transient has its own manual (transient.org/.texi), but that's missing
>>>>> from the version shipped with Emacs.  Could we add the manual to the
>>>>> Emacs release?
>>>> 
>>>> Sounds like a good idea to me; adding Jonas to the CCs.
>>> 
>>> Agreed.  I was planning to create a new release first and merge that
>>> into "emacs-28" before doing so, but it seems the ship has sailed.
>>> 
>>> On the other hand it contains important bug fixes (but also new
>>> features) and nothing on "emacs-28" uses it yet.  So maybe it would
>>> still be okay to update even during the pre-release phase; I don't know.
>>> Removing it from "emacs-28" and only releasing it in 29 (or maybe 28.2)
>>> might also be an option.
>>
>> Or maybe it would be feasible to add the manual version that
>> corresponds to the Emacs 28 version?
>
> Yes.  Just saying that wasn't the plan.  (And that won't make the bugs
> go away.  And some of them were quite severe, but I believe that those
> that made it necessary to kill Emacs from the outside have at least
> been neutered, i.e. there's still an error but Emacs remains usable.)

I had another look and I think we are safe going with v0.3.7.  While
that comes after the "big refactor to squash the big bug" changes it
does comes right after the "remove booby trap" commit.  Actually I
think that commit is why I released v0.3.7.  ;P

     Jonas

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Date: Tue, 15 Feb 2022 17:53:26 +0100
> Cc: 53316@debbugs.gnu.org
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > Philipp Stephani <p.stephani2@gmail.com> writes:
> >
> >> Transient has its own manual (transient.org/.texi), but that's missing
> >> from the version shipped with Emacs.  Could we add the manual to the
> >> Emacs release?
> >
> > Sounds like a good idea to me; adding Jonas to the CCs.
> 
> I've just added.
> 
> I've added the generated texi file not the org source because to export
> that correctly my ox-texinfo+ package is required.  A new implementation
> of the main feature of that package recently made it into Org's main
> branch, so once the next feature release is merged into Emacs' master
> branch, then we can track the org file instead (on master).

Thanks.

However, if the Texinfo file I just spent an hour fixing was produced
from the Org source, then either the Org source or the conversion from
Org to Texinfo "needs work", because the result had many issues, as
you can see.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Glenn Morris]

Jonas Bernoulli wrote:

> I've added the generated texi file not the org source because to export
> that correctly my ox-texinfo+ package is required.

I believe it is a bug for Emacs not to distribute the preferred form for
modification.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Jonas Bernoulli]

Eli Zaretskii <eliz@gnu.org> writes:

>> I've just added [it].

> Thanks.
>
> However, if the Texinfo file I just spent an hour fixing was produced
> from the Org source, then either the Org source or the conversion from
> Org to Texinfo "needs work", because the result had many issues, as
> you can see.

Some of these are the exporters fault, many others are not.

In any case, thanks for identifying both kinds of issues.
I will probably come back with some questions.

This common issue is already fixed for the manual of the development
version.

-incomplete prefix key sequence @code{C-x}.  This only affects the current
+incomplete prefix key sequence @kbd{C-x}.  This only affects the current

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Jonas Bernoulli]

Glenn Morris <rgm@gnu.org> writes:

> Jonas Bernoulli wrote:
>
>> I've added the generated texi file not the org source because to export
>> that correctly my ox-texinfo+ package is required.
>
> I believe it is a bug for Emacs not to distribute the preferred form for
> modification.

Since ox-texinfo+.el has already been superseded by a better
implementation I don't think it should be added to Emacs.

And I don't think it makes sense to add the org file if some of the
code needed to produce the texi file are not available inside Emacs.
Eli would just have had to fix many more issues manually.

I would be in favor of moving the improved implementation from Org's
"main" branch to the branch that is synced with Emacs' "emacs-28"
branch, but as far as I know its too late for that because of the
feature freeze.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Eli Zaretskii]

> From: Jonas Bernoulli <jonas@bernoul.li>
> Cc: larsi@gnus.org, p.stephani2@gmail.com, 53316@debbugs.gnu.org
> Date: Tue, 15 Feb 2022 22:39:05 +0100
> 
> This common issue is already fixed for the manual of the development
> version.
> 
> -incomplete prefix key sequence @code{C-x}.  This only affects the current
> +incomplete prefix key sequence @kbd{C-x}.  This only affects the current

Good to know.  Another common issue is use of SOMETHING instead of
@var{something}.  Yet another problem is quoting "like this" instead
of ``like this''.  Also, "see @ref" is over-used: in many places it
should be either @xref or @pxref instead.

Thanks.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Glenn Morris]

>> I believe it is a bug for Emacs not to distribute the preferred form for
>> modification.

See previous identical issue https://debbugs.gnu.org/45143
Especially https://debbugs.gnu.org/45143#14

  That is a moral fault. We must distribute the real source code, always
  without exception.

> And I don't think it makes sense to add the org file if some of the
> code needed to produce the texi file are not available inside Emacs.
> Eli would just have had to fix many more issues manually.

Then IMO this manual should not be distributed with Emacs, until such
time as the required build machinery can be.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Wed, 16 Feb 2022 16:09:39 -0500
> Cc: Lars Ingebrigtsen <larsi@gnus.org>,
>  Philipp Stephani <p.stephani2@gmail.com>, 53316@debbugs.gnu.org
> 
> > And I don't think it makes sense to add the org file if some of the
> > code needed to produce the texi file are not available inside Emacs.
> > Eli would just have had to fix many more issues manually.
> 
> Then IMO this manual should not be distributed with Emacs, until such
> time as the required build machinery can be.

That's IMNSHO an extremist POV with which I cannot disagree more.
It's tantamount to saying that if we have a bug in Emacs, we cannot
make a release until we fix it.

As long as we are working on this issue, and intend to eventually
provide the Org source in the distribution, I see no reason to remove
the manual from the distribution.  The Texinfo source will be in the
tarball, can be used to make changes in the manual, and after my
extensive changes one can no longer say that Texinfo is not the real
source anyway.

We should strive to fix the issues with generating the manual from Org
on master, before Emacs 29 is released.  Jonas, if you need any help
with that, please holler.

bug#53316: 28.0.91; Missing Transient manual in Emacs

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

Would someone please post a review of what this issue is about?
I have not been following it -- I thought it was a technical issue
and assumed people would find a good solution -- but now it seems
maybe it goes beyond the level of technical.

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

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: rgm@gnu.org, larsi@gnus.org, jonas@bernoul.li,
> 	p.stephani2@gmail.com, 53316@debbugs.gnu.org
> Date: Fri, 18 Feb 2022 23:57:42 -0500
> 
> Would someone please post a review of what this issue is about?
> I have not been following it -- I thought it was a technical issue
> and assumed people would find a good solution -- but now it seems
> maybe it goes beyond the level of technical.

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.

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.
Work continues on solving the problems in the Org sources and in the
conversion programs, with the goal of switching to the Org sources
when this job is done to our satisfaction.

I think having this manual, with all its deficiencies and issues, in
the Emacs 28 tarball is better than not having any manual.  Transient
is a very non-trivial package, and I believe it would be impossible
for users to use it without a decent manual.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Glenn Morris]

My summary would be:

Transient is an Emacs library developed externally to Emacs.
A copy has now been added to Emacs for Emacs 28.
(I assume there is no intent to move development to Emacs.)
It has a manual written in Org format.
The Texinfo file is automatically generated from that Org source.

Originally the Transient manual was not in Emacs at all.
Now the generated Texinfo file has been added to Emacs, but not the
original Org source.


I previously reported a similar case as
  Subject: bug#45143: Missing source for some doc/misc manuals?
for the manuals for Org and Modus Themes.

You commented in several messages in Feb 2021, such as
  Message-Id: <E1lBsmZ-0004KA-FC@fencepost.gnu.org>
  Message-Id: <E1lE4bt-0006mL-5e@fencepost.gnu.org>


Since the generated transient.texi file was added to Emacs, it has been
manually edited, because, as was already known, Texi-generated-from-Org
isn't as good as hand-written Texi.
(I assume there is no intent for the upstream Transient to switch its
manual from being written in Org to being written in Texinfo,
in the same way that neither Org nor Modus Themes did.)


To resolve bug#45143, I implemented Make machinery in Emacs to generate
.texi files for those manuals from their Org sources. (Sadly these changes
were not included in Emacs 27.2, so that release does not IMO
include the preferred form for the Org manual.)


Apparently generating transient.texi from transient.org requires some
changes to Org itself, which currently only exist in upstream Org, not
in Emacs master or release branch. So it isn't possible to generate the
texi file for this package with just the Emacs sources.

bug#53316: 28.0.91; Missing Transient manual in Emacs

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

  > 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.  To distribute a compiled form of anything
without its real source code would violate our principles.
Furthermore, anyone who redistributes that Emacs release would
likewise be distributing a compiled form of this manual without its
real source code -- and since perse would not be the copyright holder,
that would violate the license.

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.

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

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

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.


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

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.

bug#53316: 28.0.91; Missing Transient manual in Emacs

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

  > Transient is not just a manual, Transient is an Emacs Lisp package,

I know.

    > Removing its manual is only acceptable to me if we also remove
    > the package and all its uses.

Lots of packages don't have manuals.  Indeed, it is undesirable not to
have the Texinfo manual, but not a disaster.

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

I see.  Well, this is ok, in terms of principles.

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

  > Fof future releases, we indeed hope to see the problems of
  > conversion from Org resolved,

That would be a very good advance; but because it's difficult and
because I've seen people neglect the issue before, could you ask
the people doing this to show me the spec they want to implement?


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

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Jonas Bernoulli]

Richard Stallman <rms@gnu.org> writes:
> That would be a very good advance; but because it's difficult and
> because I've seen people neglect the issue before, could you ask
> the people doing this to show me the spec they want to implement?

The exporter currently can do this and similar:
  =code=    =>    @code{code}
once I am done it will be able to optionally do this and similar:
  $var$     =>    @var{var}

It will take some time because it has to be implemented in a way that
satisfies the Org maintainers.  I am also not excited to work on it
because I thought I was finally done getting my changes merged into
Org, which was a slow and somewhat painful experience.  Immediately
turns out that no, I have to further improve the exporter.

Being asked for a spec is annoying, and so is the assumption that I
won't do the work.

bug#53316: 28.0.91; Missing Transient manual in Emacs

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: rgm@gnu.org, larsi@gnus.org, jonas@bernoul.li,
> 	p.stephani2@gmail.com, 53316@debbugs.gnu.org
> Date: Wed, 23 Feb 2022 01:45:33 -0500
> 
>     > Removing its manual is only acceptable to me if we also remove
>     > the package and all its uses.
> 
> Lots of packages don't have manuals.  Indeed, it is undesirable not to
> have the Texinfo manual, but not a disaster.

It is in this case, IMO.  I suggest that you take a quick look at
transient.el and consider whether it is easy to grasp without a decent
manual.  My firm opinion is that it is very hard for the uninitiated.

>   > For future releases, we indeed hope to see the problems of
>   > conversion from Org resolved,
> 
> That would be a very good advance; but because it's difficult and
> because I've seen people neglect the issue before, could you ask
> the people doing this to show me the spec they want to implement?

Jonas explicitly said he is working on this, so I find it hard to
believe that this won't be solved soon enough, worst case in time for
Emacs 29.

bug#53316: 28.0.91; Missing Transient manual in Emacs

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

  > The exporter currently can do this and similar:
  >   =code=    =>    @code{code}
  > once I am done it will be able to optionally do this and similar:
  >   $var$     =>    @var{var}

That syntax is convenient to use, but hard to extend to cover all the
Texinfo markup facilities.  There are LOTS of them.

  > Being asked for a spec is annoying, and so is the assumption that I
  > won't do the work.

Please don't take it personally.  It's not about you.  Designing the
interface is the hardest part of this, and other efforts have ended
up in a dead end.

What's hard is finding syntax for so many markup constructs.
I don't think the simple approach with one punctuation character
can handle it.  Also, Texinfo markup constructs nest.

I have seen systems inspired by markdown that were meant to be used
for manuals.  Each one handled only a subset of the jobs that Texinfo
markup constructs do.  The markup approach is so limiting that it
doesn't offer much room for syntax for a greater number of constructs.

I've found that people tend to implement a subset, and it is easy to
find usable syntax for a small number of constructs.  But there is no
natural way to extend it to do the whole job.  In effect, doing this
for a subset "first", expecting to add the others later, means a risk
of ending up in a dead end.

I'm sure you will finish this job, if you start with a plan for
handling all the markup constructs.

Have you got a list of Texinfo constructs to support?

If there is no way Org format can handle the repertoire of constructs
that we want for our manuals, we should not use Org format for the
source for a manual.  We should use Texinfo format.

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