GNU bug report logs - #45143
Missing source for some doc/misc manuals?

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 45143 in the body.
You can then email your comments to 45143 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: submit <at> debbugs.gnu.org
Subject: Missing source for some doc/misc manuals?
Date: Wed, 09 Dec 2020 12:41:06 -0500

Package: emacs
Version: 28.0.50
Severity: important

It seems that the preferred form for some manuals in doc/misc is an org
file, not a texi file. Doesn't this mean that Emacs has to distribute
those files, and the associated build machinery?

This seems to apply to at least:
doc/misc/modus-themes.texi
doc/misc/org.texi

Ref:
https://gitlab.com/protesilaos/modus-themes/-/tree/main/doc
https://code.orgmode.org/bzg/org-mode/src/master/doc

Message #8 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals?
Date: Tue, 15 Dec 2020 13:17:16 -0500

PS to me, this resembles the cedet grammar files issue that necessitated
the release of 23.2a and 23.3a.

Message #11 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals?
Date: Sun, 31 Jan 2021 16:47:10 -0500

If this is a licensing violation I would hope it is fixed for the next release;
if it isn't you can close it as wontfix.

Message #14 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Wed, 17 Feb 2021 00:40:48 -0500

rms said, off-list:

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

  Would you please report this to bug-gnu-emacs and put moral-issue in
  the Subject field?

Message #17 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Wed, 17 Feb 2021 09:45:28 +0100

>>>>> On Wed, 17 Feb 2021 00:40:48 -0500, Glenn Morris <rgm <at> gnu.org> said:

    Glenn> rms said, off-list:

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

    Glenn>   Would you please report this to bug-gnu-emacs and put moral-issue in
    Glenn>   the Subject field?

Which manuals?

Robert

Message #20 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: Glenn Morris <rgm <at> gnu.org>, 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Wed, 17 Feb 2021 14:27:02 +0000

Robert Pluim <rpluim <at> gmail.com> writes:

>>>>>> On Wed, 17 Feb 2021 00:40:48 -0500, Glenn Morris <rgm <at> gnu.org> said:
>
>     Glenn> rms said, off-list:
>
>     Glenn>   That is a moral fault.  We must distribute the real source code,
>     Glenn>   always without exception.
>
>     Glenn>   Would you please report this to bug-gnu-emacs and put moral-issue in
>     Glenn>   the Subject field?
>
> Which manuals?

See upthread and the OP: https://bugs.gnu.org/45143#5

-- 
Basil

Message #23 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: Glenn Morris <rgm <at> gnu.org>, 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Wed, 17 Feb 2021 15:41:09 +0100

>>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <contovob <at> tcd.ie> said:

    Basil> Robert Pluim <rpluim <at> gmail.com> writes:
    >>>>>>> On Wed, 17 Feb 2021 00:40:48 -0500, Glenn Morris <rgm <at> gnu.org> said:
    >> 
    Glenn> rms said, off-list:
    >> 
    Glenn> That is a moral fault.  We must distribute the real source code,
    Glenn> always without exception.
    >> 
    Glenn> Would you please report this to bug-gnu-emacs and put moral-issue in
    Glenn> the Subject field?
    >> 
    >> Which manuals?

    Basil> See upthread and the OP: https://bugs.gnu.org/45143#5

Ah, sorry, I thought Glenn was opening a new bug.

Checking in the org-mode .org file shouldn't be an issue. I guess we
also need the Makefile rules to turn it into an info file?

Robert

Message #26 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: contovob <at> tcd.ie, rgm <at> gnu.org, 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Wed, 17 Feb 2021 18:09:31 +0200

> From: Robert Pluim <rpluim <at> gmail.com>
> Date: Wed, 17 Feb 2021 15:41:09 +0100
> Cc: Glenn Morris <rgm <at> gnu.org>, 45143 <at> debbugs.gnu.org
> 
> >>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <contovob <at> tcd.ie> said:
> 
> Checking in the org-mode .org file shouldn't be an issue. I guess we
> also need the Makefile rules to turn it into an info file?

Not necessarily.  having the instructions in the README should be
enough.  (Making Info from .org as part of the build could be
problematic, since we need a functional Emacs for that.  While that
could be done, I don't see why we should bother.)

Message #29 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: contovob <at> tcd.ie, rgm <at> gnu.org, 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Wed, 17 Feb 2021 17:15:58 +0100

>>>>> On Wed, 17 Feb 2021 18:09:31 +0200, Eli Zaretskii <eliz <at> gnu.org> said:

    >> From: Robert Pluim <rpluim <at> gmail.com>
    >> Date: Wed, 17 Feb 2021 15:41:09 +0100
    >> Cc: Glenn Morris <rgm <at> gnu.org>, 45143 <at> debbugs.gnu.org
    >> 
    >> >>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <contovob <at> tcd.ie> said:
    >> 
    >> Checking in the org-mode .org file shouldn't be an issue. I guess we
    >> also need the Makefile rules to turn it into an info file?

    Eli> Not necessarily.  having the instructions in the README should be
    Eli> enough.  (Making Info from .org as part of the build could be
    Eli> problematic, since we need a functional Emacs for that.  While that
    Eli> could be done, I don't see why we should bother.)

We need a functional emacs to byte-compile files as well, I donʼt see
why this is any different.

In my mind, source code without the accompanying build instructions is
incomplete (unless you count the README as those instructions).

Robert

Message #32 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: contovob <at> tcd.ie, rgm <at> gnu.org, 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Wed, 17 Feb 2021 19:28:13 +0200

> From: Robert Pluim <rpluim <at> gmail.com>
> Cc: contovob <at> tcd.ie,  rgm <at> gnu.org,  45143 <at> debbugs.gnu.org
> Date: Wed, 17 Feb 2021 17:15:58 +0100
> 
>     Eli> Not necessarily.  having the instructions in the README should be
>     Eli> enough.  (Making Info from .org as part of the build could be
>     Eli> problematic, since we need a functional Emacs for that.  While that
>     Eli> could be done, I don't see why we should bother.)
> 
> We need a functional emacs to byte-compile files as well, I donʼt see
> why this is any different.

It's a complication, since we generally build the manuals right at the
beginning.

> In my mind, source code without the accompanying build instructions is
> incomplete (unless you count the README as those instructions).

I do count README as instructions for this purpose.

Message #35 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Fri, 19 Feb 2021 00:34:36 -0500

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

Can you please report the details of this bug?
For instance, the file names?


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

Message #38 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Richard Stallman <rms <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Fri, 19 Feb 2021 00:57:38 -0500

Richard Stallman wrote:

> Can you please report the details of this bug?

All the details were in my original report, which you seem to have missed.

    To: submit <at> debbugs.gnu.org
    Subject: Missing source for some doc/misc manuals?
    Date: Wed, 09 Dec 2020 12:41:06 -0500
    Message-ID: <3y4kku7u8d.fsf <at> fencepost.gnu.org>

    Package: emacs
    Version: 28.0.50
    Severity: important

    It seems that the preferred form for some manuals in doc/misc is an org
    file, not a texi file. Doesn't this mean that Emacs has to distribute
    those files, and the associated build machinery?

    This seems to apply to at least:
    doc/misc/modus-themes.texi
    doc/misc/org.texi

    Ref:
    https://gitlab.com/protesilaos/modus-themes/-/tree/main/doc
    https://code.orgmode.org/bzg/org-mode/src/master/doc

Message #41 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Missing source for some doc/misc manuals (moral-issue)
Date: Sun, 21 Feb 2021 01:15:22 -0500

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


  > All the details were in my original report, which you seem to have missed.

As an afterthought I realized there might be another problem
even after we include their source.  I will look and see if that is so.
Thanks for sending this again:

    This seems to apply to at least:
    doc/misc/modus-themes.texi
    doc/misc/org.texi

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

Message #44 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Incorrect markup in some doc/misc manuals
Date: Sun, 21 Feb 2021 01:15:25 -0500

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

Theis problem is in doc/misc/modus-themes.texi,
but I suspect that doc/misc/org.texi has it too.

The problem is that the file uses the wrong Texinfo markup in some
places.  I suspect that the source markup language, from which this
Texinfo text is generated, doesn't have the ability to make all the
distinctions Texinfo needs.


Here's an example from modus-themes.texi:

    Prior to querying any package archive, make sure to have updated the
    index, with @samp{M-x package-refresh-contents}.  Then all you need to do is
    type @samp{M-x package-install} and specify the theme of your choice.

@samp is incorrect here.  If it is M-x package-install RET, that is
keyboard input so it ashould be written in @kbd.  On the other hand,
package-install without M-x and RET is a command name and should be
inside @code.

Later on:

    If you set @samp{calendar-latitude} and @samp{calendar-longitude} (defined in the
    built-in @samp{solar.el} library---read it with @samp{M-x find-library}), you c

calendar-longitude is a symbol; it should be in @code.
solar.el is a file name; it should be in @file.

    The symbols ``subtle'' and ``intense'' will apply a combination of accented

Those symbol names should be in @code, not doublequotes.





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

Message #47 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Protesilaos Stavrou <info <at> protesilaos.com>
To: Richard Stallman <rms <at> gnu.org>
Cc: Glenn Morris <rgm <at> gnu.org>, 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Sun, 21 Feb 2021 13:01:46 +0200

On 2021-02-21, 01:15 -0500, Richard Stallman <rms <at> gnu.org> wrote:

> Theis problem is in doc/misc/modus-themes.texi,
> but I suspect that doc/misc/org.texi has it too.
>
> The problem is that the file uses the wrong Texinfo markup in some
> places.  I suspect that the source markup language, from which this
> Texinfo text is generated, doesn't have the ability to make all the
> distinctions Texinfo needs.

Related: bug#45141 reported by Glenn Morris.

With regard to the modus-themes, I am indeed building the manual from an
Org file.  I have not found any way to fix those issues in advance (at
the Org level), so I am willing to do so manually when I am about to
send a patch to the Emacs maintainers.

The blocking issue, however, is that there is no progress on bug#45068,
which is about updating the themes to their latest version.  That
includes changes to the manual.  You can read the recap here:
<https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45068#86> (please bear in
mind that more development time has been invested since then, meaning
that we are closer to version 1.2.0 of the themes).

I am willing to help in any way I can, though changing the Emacs
infrastructure is still beyond my skill level.

-- 
Protesilaos Stavrou
protesilaos.com

Message #50 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Sun, 21 Feb 2021 22:11:29 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Date: Sun, 21 Feb 2021 01:15:25 -0500
> Cc: 45143 <at> debbugs.gnu.org
> 
> Theis problem is in doc/misc/modus-themes.texi,
> but I suspect that doc/misc/org.texi has it too.
> 
> The problem is that the file uses the wrong Texinfo markup in some
> places.  I suspect that the source markup language, from which this
> Texinfo text is generated, doesn't have the ability to make all the
> distinctions Texinfo needs.

I think this is because Org has some problems in supporting some of
the key Texinfo markups, such as @kbd.  This was discussed 3 years
ago, in this thread:

  https://lists.gnu.org/archive/html/emacs-devel/2018-03/msg00166.html

I don't know if Org's support for Texinfo became better since then.

Message #53 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Protesilaos Stavrou <info <at> protesilaos.com>
Cc: rgm <at> gnu.org, 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Mon, 22 Feb 2021 01:22:21 -0500

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

  > With regard to the modus-themes, I am indeed building the manual from an
  > Org file.  I have not found any way to fix those issues in advance (at
  > the Org level), so I am willing to do so manually when I am about to
  > send a patch to the Emacs maintainers.

I appreciate your willingness to do this work, but this situation is a
problem, because there is no such thing as the source file for that
manual.  The Texinfo file is not the real source file, since you don't
really do editing in it.  The Org file is not the real source file
since you can't compile it automatically.

We need to have a real source file!

Can you treat the Texinfo file as the source,
and do your editing in that.

Alternatively, could you enhance Org format so you can
generate the Texinfo file automatically from it, with all
the proper Texinfo markup?

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

Message #56 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Protesilaos Stavrou <info <at> protesilaos.com>
To: Richard Stallman <rms <at> gnu.org>
Cc: rgm <at> gnu.org, 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Mon, 22 Feb 2021 18:38:55 +0200

On 2021-02-22, 01:22 -0500, Richard Stallman <rms <at> gnu.org> wrote:

>   > With regard to the modus-themes, I am indeed building the manual from an
>   > Org file.  I have not found any way to fix those issues in advance (at
>   > the Org level), so I am willing to do so manually when I am about to
>   > send a patch to the Emacs maintainers.
>
> I appreciate your willingness to do this work, but this situation is a
> problem, because there is no such thing as the source file for that
> manual.  The Texinfo file is not the real source file, since you don't
> really do editing in it.  The Org file is not the real source file
> since you can't compile it automatically.
>
> We need to have a real source file!
>
> Can you treat the Texinfo file as the source,
> and do your editing in that.

I think we need to distinguish between two cases:

1. The version of the Modus themes' manual that ships with Emacs.  This
   is exclusively in .texi format.

2. The version that is distributed through my git repository.  This is
   written in .org and also distributed as a derivative .info file.  A
   website version is on offer as well (no javascript required).[1]

With regard to case 1, I agree that we should treat Texinfo as the
source: it is all we provide.  This is why I am willing to edit it
manually in those cases where the Org export falls short, as we have
already established.  What prevents me from doing so right now is the
pending upgrade of the themes in Emacs from their 0.13.0 version to what
I currently have, which will soon be 1.2.0 (three releases ahead).

If you think that I should patch the manual of case 1 right now, without
waiting for the sync between core Emacs and my repo, then I will do it.
If, however, you believe we can afford to wait a while longer, I would
prefer to edit the version of the manual that corresponds to the themes'
forthcoming version 1.2.0.  It makes it easier to maintain my project
when I do not have to deal with branching paths.

As for case 2, I would like to continue to treat the .org as the
original source file.  For me Org is easier to work with than Texinfo.
It is also better for end users who, I presume, are more likely not to
be familiar with the .texi markup.  Given my expressed willingness to
make the requisite changes in the .texi file of case 1, I see no problem
in opting for such a preference.

If you disagree, please inform me about it (or point me to the right
documentation) and I will do my best to adopt a better practice.

At any rate, I must stress that there is no intent whatsoever to
obfuscate any piece of information or otherwise hide anything from the
user: everything is already available and is licensed under libre
licenses.  Whatever issue we have been discussing here is caused by
infrastructure-level constraints that should be overcome with some
effort.

> Alternatively, could you enhance Org format so you can
> generate the Texinfo file automatically from it, with all
> the proper Texinfo markup?

That would be nice.  I am afraid I cannot do that though: I do not have
intimate knowledge of the Org export facility and the Texinfo syntax.

[1]: <https://protesilaos.com/modus-themes/>.

-- 
Protesilaos Stavrou
protesilaos.com

Message #59 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Wed, 24 Feb 2021 01:49:29 -0500

[[[ 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 think this is because Org has some problems in supporting some of
  > the key Texinfo markups, such as @kbd.

You are surely right that that is why the problem exists,
but it still needs to be fixed.

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

Message #62 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Protesilaos Stavrou <info <at> protesilaos.com>
To: Protesilaos Stavrou <info <at> protesilaos.com>
Cc: rgm <at> gnu.org, 45143 <at> debbugs.gnu.org, Richard Stallman <rms <at> gnu.org>
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Wed, 24 Feb 2021 09:38:23 +0200

Hello again!

This is in response to my previous reply, copied below.

After reading through the discussion[1] on using Org for Emacs manuals,
I have managed to make some changes to the modus-themes.org file which
generates modus-themes.texi.

You can inspect the source code with:

    git clone https://gitlab.com/protesilaos/modus-themes.git

Documentation is stored in the repo's "doc" directory.

The changes pertain to the appropriate use of Texinfo markup such as
'kbd', 'code', and 'file'.  Furthermore, the modus-themes.texi file is
now distributed as part of the source code, whereas before I was only
sharing the modus-themes.org and its derived modus-themes.info.

Those improvements will be made available for the forthcoming version
1.2.0 of the Modus themes (expected within the next few days).  Core
Emacs currently ships with the themes' 0.13.0 version, which will soon
be three releases behind.

As noted before, I want to only maintain one copy of my project, so the
bug we are currently discussing (#45143) as well as #45141 should be
contingent on #45068.  A few weeks ago, I offered a summary of what the
state of affairs on #45068 is.[2] The only change since then is the
newer version of my project.

Thank you for your time!

All the best,
Protesilaos

[1]: <https://lists.gnu.org/archive/html/emacs-devel/2018-03/msg00166.html>.
[2]: <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=45068#86>.



On 2021-02-22, 18:38 +0200, Protesilaos Stavrou <info <at> protesilaos.com> wrote:

> On 2021-02-22, 01:22 -0500, Richard Stallman <rms <at> gnu.org> wrote:
>
>>   > With regard to the modus-themes, I am indeed building the manual from an
>>   > Org file.  I have not found any way to fix those issues in advance (at
>>   > the Org level), so I am willing to do so manually when I am about to
>>   > send a patch to the Emacs maintainers.
>>
>> I appreciate your willingness to do this work, but this situation is a
>> problem, because there is no such thing as the source file for that
>> manual.  The Texinfo file is not the real source file, since you don't
>> really do editing in it.  The Org file is not the real source file
>> since you can't compile it automatically.
>>
>> We need to have a real source file!
>>
>> Can you treat the Texinfo file as the source,
>> and do your editing in that.
>
> I think we need to distinguish between two cases:
>
> 1. The version of the Modus themes' manual that ships with Emacs.  This
>    is exclusively in .texi format.
>
> 2. The version that is distributed through my git repository.  This is
>    written in .org and also distributed as a derivative .info file.  A
>    website version is on offer as well (no javascript required).[1]
>
> With regard to case 1, I agree that we should treat Texinfo as the
> source: it is all we provide.  This is why I am willing to edit it
> manually in those cases where the Org export falls short, as we have
> already established.  What prevents me from doing so right now is the
> pending upgrade of the themes in Emacs from their 0.13.0 version to what
> I currently have, which will soon be 1.2.0 (three releases ahead).
>
> If you think that I should patch the manual of case 1 right now, without
> waiting for the sync between core Emacs and my repo, then I will do it.
> If, however, you believe we can afford to wait a while longer, I would
> prefer to edit the version of the manual that corresponds to the themes'
> forthcoming version 1.2.0.  It makes it easier to maintain my project
> when I do not have to deal with branching paths.
>
> As for case 2, I would like to continue to treat the .org as the
> original source file.  For me Org is easier to work with than Texinfo.
> It is also better for end users who, I presume, are more likely not to
> be familiar with the .texi markup.  Given my expressed willingness to
> make the requisite changes in the .texi file of case 1, I see no problem
> in opting for such a preference.
>
> If you disagree, please inform me about it (or point me to the right
> documentation) and I will do my best to adopt a better practice.
>
> At any rate, I must stress that there is no intent whatsoever to
> obfuscate any piece of information or otherwise hide anything from the
> user: everything is already available and is licensed under libre
> licenses.  Whatever issue we have been discussing here is caused by
> infrastructure-level constraints that should be overcome with some
> effort.
>
>> Alternatively, could you enhance Org format so you can
>> generate the Texinfo file automatically from it, with all
>> the proper Texinfo markup?
>
> That would be nice.  I am afraid I cannot do that though: I do not have
> intimate knowledge of the Org export facility and the Texinfo syntax.
>
> [1]: <https://protesilaos.com/modus-themes/>.

-- 
Protesilaos Stavrou
protesilaos.com

Message #65 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Wed, 24 Feb 2021 17:09:58 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Cc: 45143 <at> debbugs.gnu.org
> Date: Wed, 24 Feb 2021 01:49:29 -0500
> 
>   > I think this is because Org has some problems in supporting some of
>   > the key Texinfo markups, such as @kbd.
> 
> You are surely right that that is why the problem exists,
> but it still needs to be fixed.

Of course, no argument here.  My point is that until the Org's Texinfo
export is fixed so that it produces better Texinfo, these problems
will be inevitable.  The issues described and discussed in that past
thread were not fixed, AFAIK.

Message #68 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Protesilaos Stavrou <info <at> protesilaos.com>
Cc: rgm <at> gnu.org, info <at> protesilaos.com, 45143 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Wed, 24 Feb 2021 17:13:09 +0200

> From: Protesilaos Stavrou <info <at> protesilaos.com>
> Date: Wed, 24 Feb 2021 09:38:23 +0200
> Cc: rgm <at> gnu.org, 45143 <at> debbugs.gnu.org, Richard Stallman <rms <at> gnu.org>
> 
> After reading through the discussion[1] on using Org for Emacs manuals,
> I have managed to make some changes to the modus-themes.org file which
> generates modus-themes.texi.
> 
> You can inspect the source code with:
> 
>     git clone https://gitlab.com/protesilaos/modus-themes.git
> 
> Documentation is stored in the repo's "doc" directory.
> 
> The changes pertain to the appropriate use of Texinfo markup such as
> 'kbd', 'code', and 'file'.  Furthermore, the modus-themes.texi file is
> now distributed as part of the source code, whereas before I was only
> sharing the modus-themes.org and its derived modus-themes.info.
> 
> Those improvements will be made available for the forthcoming version
> 1.2.0 of the Modus themes (expected within the next few days).  Core
> Emacs currently ships with the themes' 0.13.0 version, which will soon
> be three releases behind.

Thanks, but please also submit those improvements to Org's Texinfo
export to the Org developers, so that other manuals written in org
could also benefit from this improved Texinfo support.

Message #71 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Protesilaos Stavrou <info <at> protesilaos.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: rgm <at> gnu.org, 45143 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Thu, 25 Feb 2021 08:04:23 +0200

On 2021-02-24, 17:13 +0200, Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Protesilaos Stavrou <info <at> protesilaos.com>
>> Date: Wed, 24 Feb 2021 09:38:23 +0200
>> Cc: rgm <at> gnu.org, 45143 <at> debbugs.gnu.org, Richard Stallman <rms <at> gnu.org>
>> 
>> After reading through the discussion[1] on using Org for Emacs manuals,
>> I have managed to make some changes to the modus-themes.org file which
>> generates modus-themes.texi.
>> 
>> You can inspect the source code with:
>> 
>>     git clone https://gitlab.com/protesilaos/modus-themes.git
>> 
>> Documentation is stored in the repo's "doc" directory.
>> 
>> The changes pertain to the appropriate use of Texinfo markup such as
>> 'kbd', 'code', and 'file'.  Furthermore, the modus-themes.texi file is
>> now distributed as part of the source code, whereas before I was only
>> sharing the modus-themes.org and its derived modus-themes.info.
>> 
>> Those improvements will be made available for the forthcoming version
>> 1.2.0 of the Modus themes (expected within the next few days).  Core
>> Emacs currently ships with the themes' 0.13.0 version, which will soon
>> be three releases behind.
>
> Thanks, but please also submit those improvements to Org's Texinfo
> export to the Org developers, so that other manuals written in org
> could also benefit from this improved Texinfo support.

Yes, sure!  I will go through the Org manual and check what can be done.

Though I think Richard's and Glenn's original point was that the Org
project uses the ".org" file as its original source in its own git
repository ("org-manual.org"), whereas it distributes ".texi" with
emacs.git ("org.texi")---so what is in core Emacs is technically not the
original source.

That was the issue with my themes and is why I am now sharing the
".texi" in addition to the ".org".  If I notice any further
inconsistencies, I will address them.

-- 
Protesilaos Stavrou
protesilaos.com

Message #74 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Protesilaos Stavrou <info <at> protesilaos.com>
Cc: rgm <at> gnu.org, 45143 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Thu, 25 Feb 2021 16:40:56 +0200

> From: Protesilaos Stavrou <info <at> protesilaos.com>
> Cc: rgm <at> gnu.org,  45143 <at> debbugs.gnu.org,  rms <at> gnu.org
> Date: Thu, 25 Feb 2021 08:04:23 +0200
> 
> Though I think Richard's and Glenn's original point was that the Org
> project uses the ".org" file as its original source in its own git
> repository ("org-manual.org"), whereas it distributes ".texi" with
> emacs.git ("org.texi")---so what is in core Emacs is technically not the
> original source.

Yes.  But in order for us to provide the original source, we need to
make sure the produced Texinfo will be up to our standards and
conventions, which means Org's Texinfo export must support the
standard markups, such as @kbd, @file, etc..

Message #77 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Fri, 26 Feb 2021 01:32:07 -0500

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

  > Of course, no argument here.  My point is that until the Org's Texinfo
  > export is fixed so that it produces better Texinfo, these problems
  > will be inevitable.

The underlying issues have not been addressed, but there are various
ways to fix this problem.  Protesilaos told me has fixed it,
and maybe it is fixed -- I am waiting to learn the details.

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

Message #80 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Fri, 26 Feb 2021 09:45:36 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Cc: 45143 <at> debbugs.gnu.org
> Date: Fri, 26 Feb 2021 01:32:07 -0500
> 
>   > Of course, no argument here.  My point is that until the Org's Texinfo
>   > export is fixed so that it produces better Texinfo, these problems
>   > will be inevitable.
> 
> The underlying issues have not been addressed, but there are various
> ways to fix this problem.  Protesilaos told me has fixed it,
> and maybe it is fixed -- I am waiting to learn the details.

He fixed them by installing local changes to Org's export as part of
hist manual source in Org.  I suggested that he submits those changes
to Org developers, with the goal of making the official Org Texinfo
export support @kbd etc., and this bring it closer to the goal of
producing higher-quality Texinfo.

Message #83 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 45143 <at> debbugs.gnu.org
Cc: Protesilaos Stavrou <info <at> protesilaos.com>, Eli Zaretskii <eliz <at> gnu.org>,
 rms <at> gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Fri, 26 Feb 2021 22:49:41 -0500

I felt like this report wasn't going anywhere, so I fixed it
myself in 3984044ad3..b3d310fa96 and will close this report.

I could not find a version of modus-themes.org that precisely
corresponded to the modus-themes.texi in Emacs.

If there are any bugs in the change, please followup in a new report.

Please also make new reports for any issues with the quality of the texi
files generated by Org. Ideally these would be against the org-mode package.

Message #88 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 45143 <at> debbugs.gnu.org
Cc: Protesilaos Stavrou <info <at> protesilaos.com>, Eli Zaretskii <eliz <at> gnu.org>,
 rms <at> gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Fri, 26 Feb 2021 22:55:20 -0500

PS To satisfy Emacs's moral obligations, IMO this change should be in
the Emacs 27.2 release in some form, but I would prefer not to spend
more time on it myself.

Message #91 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Protesilaos Stavrou <info <at> protesilaos.com>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>, rms <at> gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Sat, 27 Feb 2021 08:29:33 +0200

On 2021-02-26, 22:49 -0500, Glenn Morris <rgm <at> gnu.org> wrote:

> I felt like this report wasn't going anywhere, so I fixed it
> myself in 3984044ad3..b3d310fa96 and will close this report.

Thank you!  So commit 3984044ad3 means that I should be contributing the
.org version of my manual from now on.

> I could not find a version of modus-themes.org that precisely
> corresponded to the modus-themes.texi in Emacs.

This is because I had made a few changes to that version that manually
fixed .texi markup and adjusted a few things to work with the emacs.git
build requirements.

For the forthcoming version 1.2.0 of my project I have, in principle,
addressed all markup-related issues and I will share this work soon
(contingent on bug#45068).  Though there will still have to be some
patches that are specific to emacs.git:

+ The "@setfilename" needs to be defined as a relative path.  This
  corresponds to the "#+TEXINFO_FILENAME:" in the Org format, which is
  not in the file now in Emacs (maybe this step can be skipped?).

+ An "@include emacsver.texi" has to be inserted right after the
  header.

+ The GNU Free Documentation License has to be added by means of
  "@include doclicense.texi".

I cannot maintain those minor extras in my git repo because they do not
work outside the build requirements of emacs.git (unless there is a way
to handle this conditionally and I am unaware of it).

-- 
Protesilaos Stavrou
protesilaos.com

Message #94 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Sat, 27 Feb 2021 11:14:39 -0500

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

  > He fixed them by installing local changes to Org's export as part of
  > hist manual source in Org.  I suggested that he submits those changes
  > to Org developers, with the goal of making the official Org Texinfo
  > export support @kbd etc., and this bring it closer to the goal of
  > producing higher-quality Texinfo.

It looks like good progress.  I will continue talking with him about
it.

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

Message #97 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Sat, 27 Feb 2021 20:20:27 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Cc: 45143 <at> debbugs.gnu.org
> Date: Sat, 27 Feb 2021 11:14:39 -0500
> 
>   > He fixed them by installing local changes to Org's export as part of
>   > hist manual source in Org.  I suggested that he submits those changes
>   > to Org developers, with the goal of making the official Org Texinfo
>   > export support @kbd etc., and this bring it closer to the goal of
>   > producing higher-quality Texinfo.
> 
> It looks like good progress.  I will continue talking with him about
> it.

Meanwhile Glenn installed changes that produce Info from Org directly,
so I think another large part of the problem is fixed.

Message #100 received at 45143 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 45143 <at> debbugs.gnu.org
Subject: Re: bug#45143: Incorrect markup in some doc/misc manuals
Date: Mon, 01 Mar 2021 00:18:57 -0500

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

  > Meanwhile Glenn installed changes that produce Info from Org directly,
  > so I think another large part of the problem is fixed.

That is useful, but if we are going to use Org format as a source
format for manuals we must make it able to make all the distinctions
we employ.  It is unacceptable, practically, as a source format if it
can't do the whole job.

This is why I am so excited by what Protesilaos has done.

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.