bug#45143: Missing source for some doc/misc manuals?

classic Classic list List threaded Threaded
28 messages Options
12
Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals?

Glenn Morris-3
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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals?

Glenn Morris-3

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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals?

Glenn Morris-3

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.



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

Glenn Morris-3

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?



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

Basil L. Contovounesios
Robert Pluim <[hidden email]> writes:

>>>>>> On Wed, 17 Feb 2021 00:40:48 -0500, Glenn Morris <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

Robert Pluim
>>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <[hidden email]> said:

    Basil> Robert Pluim <[hidden email]> writes:
    >>>>>>> On Wed, 17 Feb 2021 00:40:48 -0500, Glenn Morris <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

Eli Zaretskii
> From: Robert Pluim <[hidden email]>
> Date: Wed, 17 Feb 2021 15:41:09 +0100
> Cc: Glenn Morris <[hidden email]>, [hidden email]
>
> >>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <[hidden email]> 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.)



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

Robert Pluim
>>>>> On Wed, 17 Feb 2021 18:09:31 +0200, Eli Zaretskii <[hidden email]> said:

    >> From: Robert Pluim <[hidden email]>
    >> Date: Wed, 17 Feb 2021 15:41:09 +0100
    >> Cc: Glenn Morris <[hidden email]>, [hidden email]
    >>
    >> >>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

Eli Zaretskii
> From: Robert Pluim <[hidden email]>
> Cc: [hidden email],  [hidden email],  [hidden email]
> 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.



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

Richard Stallman
In reply to this post by Glenn Morris-3
[[[ 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)





Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

Glenn Morris-3
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: <[hidden email]>

    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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Missing source for some doc/misc manuals (moral-issue)

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


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





Reply | Threaded
Open this post in threaded view
|

bug#45143: Incorrect markup in some doc/misc manuals

Richard Stallman
In reply to this post by Glenn Morris-3
[[[ 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)





Reply | Threaded
Open this post in threaded view
|

bug#45143: Incorrect markup in some doc/misc manuals

Protesilaos Stavrou
On 2021-02-21, 01:15 -0500, Richard Stallman <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Incorrect markup in some doc/misc manuals

Eli Zaretskii
In reply to this post by Richard Stallman
> From: Richard Stallman <[hidden email]>
> Date: Sun, 21 Feb 2021 01:15:25 -0500
> Cc: [hidden email]
>
> 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.



Reply | Threaded
Open this post in threaded view
|

bug#45143: Incorrect markup in some doc/misc manuals

Richard Stallman
In reply to this post by Protesilaos Stavrou
[[[ 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)





Reply | Threaded
Open this post in threaded view
|

bug#45143: Incorrect markup in some doc/misc manuals

Protesilaos Stavrou
On 2021-02-22, 01:22 -0500, Richard Stallman <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Incorrect markup in some doc/misc manuals

Richard Stallman
In reply to this post by Eli Zaretskii
[[[ 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)





Reply | Threaded
Open this post in threaded view
|

bug#45143: Incorrect markup in some doc/misc manuals

Protesilaos Stavrou
In reply to this post by Protesilaos Stavrou
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 <[hidden email]> wrote:

> On 2021-02-22, 01:22 -0500, Richard Stallman <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

bug#45143: Incorrect markup in some doc/misc manuals

Eli Zaretskii
In reply to this post by Richard Stallman
> From: Richard Stallman <[hidden email]>
> Cc: [hidden email]
> 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.



12