* bug#45143: Missing source for some doc/misc manuals? @ 2020-12-09 17:41 Glenn Morris 2020-12-15 18:17 ` Glenn Morris 0 siblings, 1 reply; 32+ messages in thread From: Glenn Morris @ 2020-12-09 17:41 UTC (permalink / raw) To: 45143 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals? 2020-12-09 17:41 bug#45143: Missing source for some doc/misc manuals? Glenn Morris @ 2020-12-15 18:17 ` Glenn Morris 2021-01-31 21:47 ` Glenn Morris 0 siblings, 1 reply; 32+ messages in thread From: Glenn Morris @ 2020-12-15 18:17 UTC (permalink / raw) To: 45143 PS to me, this resembles the cedet grammar files issue that necessitated the release of 23.2a and 23.3a. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals? 2020-12-15 18:17 ` Glenn Morris @ 2021-01-31 21:47 ` Glenn Morris 2021-02-17 5:40 ` bug#45143: Missing source for some doc/misc manuals (moral-issue) Glenn Morris 0 siblings, 1 reply; 32+ messages in thread From: Glenn Morris @ 2021-01-31 21:47 UTC (permalink / raw) To: 45143 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-01-31 21:47 ` Glenn Morris @ 2021-02-17 5:40 ` Glenn Morris 2021-02-17 8:45 ` Robert Pluim 2021-02-19 5:34 ` Richard Stallman 0 siblings, 2 replies; 32+ messages in thread From: Glenn Morris @ 2021-02-17 5:40 UTC (permalink / raw) To: 45143 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? ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-17 5:40 ` bug#45143: Missing source for some doc/misc manuals (moral-issue) Glenn Morris @ 2021-02-17 8:45 ` Robert Pluim 2021-02-17 14:27 ` Basil L. Contovounesios 2021-02-19 5:34 ` Richard Stallman 1 sibling, 1 reply; 32+ messages in thread From: Robert Pluim @ 2021-02-17 8:45 UTC (permalink / raw) To: Glenn Morris; +Cc: 45143 >>>>> On Wed, 17 Feb 2021 00:40:48 -0500, Glenn Morris <rgm@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-17 8:45 ` Robert Pluim @ 2021-02-17 14:27 ` Basil L. Contovounesios 2021-02-17 14:41 ` Robert Pluim 0 siblings, 1 reply; 32+ messages in thread From: Basil L. Contovounesios @ 2021-02-17 14:27 UTC (permalink / raw) To: Robert Pluim; +Cc: Glenn Morris, 45143 Robert Pluim <rpluim@gmail.com> writes: >>>>>> On Wed, 17 Feb 2021 00:40:48 -0500, Glenn Morris <rgm@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-17 14:27 ` Basil L. Contovounesios @ 2021-02-17 14:41 ` Robert Pluim 2021-02-17 16:09 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Robert Pluim @ 2021-02-17 14:41 UTC (permalink / raw) To: Basil L. Contovounesios; +Cc: Glenn Morris, 45143 >>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <contovob@tcd.ie> said: Basil> Robert Pluim <rpluim@gmail.com> writes: >>>>>>> On Wed, 17 Feb 2021 00:40:48 -0500, Glenn Morris <rgm@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-17 14:41 ` Robert Pluim @ 2021-02-17 16:09 ` Eli Zaretskii 2021-02-17 16:15 ` Robert Pluim 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-02-17 16:09 UTC (permalink / raw) To: Robert Pluim; +Cc: contovob, rgm, 45143 > From: Robert Pluim <rpluim@gmail.com> > Date: Wed, 17 Feb 2021 15:41:09 +0100 > Cc: Glenn Morris <rgm@gnu.org>, 45143@debbugs.gnu.org > > >>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <contovob@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.) ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-17 16:09 ` Eli Zaretskii @ 2021-02-17 16:15 ` Robert Pluim 2021-02-17 17:28 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Robert Pluim @ 2021-02-17 16:15 UTC (permalink / raw) To: Eli Zaretskii; +Cc: contovob, rgm, 45143 >>>>> On Wed, 17 Feb 2021 18:09:31 +0200, Eli Zaretskii <eliz@gnu.org> said: >> From: Robert Pluim <rpluim@gmail.com> >> Date: Wed, 17 Feb 2021 15:41:09 +0100 >> Cc: Glenn Morris <rgm@gnu.org>, 45143@debbugs.gnu.org >> >> >>>>> On Wed, 17 Feb 2021 14:27:02 +0000, "Basil L. Contovounesios" <contovob@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-17 16:15 ` Robert Pluim @ 2021-02-17 17:28 ` Eli Zaretskii 0 siblings, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2021-02-17 17:28 UTC (permalink / raw) To: Robert Pluim; +Cc: contovob, rgm, 45143 > From: Robert Pluim <rpluim@gmail.com> > Cc: contovob@tcd.ie, rgm@gnu.org, 45143@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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-17 5:40 ` bug#45143: Missing source for some doc/misc manuals (moral-issue) Glenn Morris 2021-02-17 8:45 ` Robert Pluim @ 2021-02-19 5:34 ` Richard Stallman 2021-02-19 5:57 ` Glenn Morris 1 sibling, 1 reply; 32+ messages in thread From: Richard Stallman @ 2021-02-19 5:34 UTC (permalink / raw) To: Glenn Morris; +Cc: 45143 [[[ 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) ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-19 5:34 ` Richard Stallman @ 2021-02-19 5:57 ` Glenn Morris 2021-02-21 6:15 ` Richard Stallman 2021-02-21 6:15 ` bug#45143: Incorrect markup in some doc/misc manuals Richard Stallman 0 siblings, 2 replies; 32+ messages in thread From: Glenn Morris @ 2021-02-19 5:57 UTC (permalink / raw) To: Richard Stallman; +Cc: 45143 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@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Missing source for some doc/misc manuals (moral-issue) 2021-02-19 5:57 ` Glenn Morris @ 2021-02-21 6:15 ` Richard Stallman 2021-02-21 6:15 ` bug#45143: Incorrect markup in some doc/misc manuals Richard Stallman 1 sibling, 0 replies; 32+ messages in thread From: Richard Stallman @ 2021-02-21 6:15 UTC (permalink / raw) To: Glenn Morris; +Cc: 45143 [[[ 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) ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-19 5:57 ` Glenn Morris 2021-02-21 6:15 ` Richard Stallman @ 2021-02-21 6:15 ` Richard Stallman 2021-02-21 11:01 ` Protesilaos Stavrou 2021-02-21 20:11 ` Eli Zaretskii 1 sibling, 2 replies; 32+ messages in thread From: Richard Stallman @ 2021-02-21 6:15 UTC (permalink / raw) To: Glenn Morris; +Cc: 45143 [[[ 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) ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-21 6:15 ` bug#45143: Incorrect markup in some doc/misc manuals Richard Stallman @ 2021-02-21 11:01 ` Protesilaos Stavrou 2021-02-22 6:22 ` Richard Stallman 2021-02-21 20:11 ` Eli Zaretskii 1 sibling, 1 reply; 32+ messages in thread From: Protesilaos Stavrou @ 2021-02-21 11:01 UTC (permalink / raw) To: Richard Stallman; +Cc: Glenn Morris, 45143 On 2021-02-21, 01:15 -0500, Richard Stallman <rms@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-21 11:01 ` Protesilaos Stavrou @ 2021-02-22 6:22 ` Richard Stallman 2021-02-22 16:38 ` Protesilaos Stavrou 0 siblings, 1 reply; 32+ messages in thread From: Richard Stallman @ 2021-02-22 6:22 UTC (permalink / raw) To: Protesilaos Stavrou; +Cc: rgm, 45143 [[[ 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) ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-22 6:22 ` Richard Stallman @ 2021-02-22 16:38 ` Protesilaos Stavrou 2021-02-24 7:38 ` Protesilaos Stavrou 0 siblings, 1 reply; 32+ messages in thread From: Protesilaos Stavrou @ 2021-02-22 16:38 UTC (permalink / raw) To: Richard Stallman; +Cc: rgm, 45143 On 2021-02-22, 01:22 -0500, Richard Stallman <rms@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-22 16:38 ` Protesilaos Stavrou @ 2021-02-24 7:38 ` Protesilaos Stavrou 2021-02-24 15:13 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Protesilaos Stavrou @ 2021-02-24 7:38 UTC (permalink / raw) To: Protesilaos Stavrou; +Cc: rgm, 45143, Richard Stallman 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@protesilaos.com> wrote: > On 2021-02-22, 01:22 -0500, Richard Stallman <rms@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-24 7:38 ` Protesilaos Stavrou @ 2021-02-24 15:13 ` Eli Zaretskii 2021-02-25 6:04 ` Protesilaos Stavrou 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-02-24 15:13 UTC (permalink / raw) To: Protesilaos Stavrou; +Cc: rgm, info, 45143, rms > From: Protesilaos Stavrou <info@protesilaos.com> > Date: Wed, 24 Feb 2021 09:38:23 +0200 > Cc: rgm@gnu.org, 45143@debbugs.gnu.org, Richard Stallman <rms@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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-24 15:13 ` Eli Zaretskii @ 2021-02-25 6:04 ` Protesilaos Stavrou 2021-02-25 14:40 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Protesilaos Stavrou @ 2021-02-25 6:04 UTC (permalink / raw) To: Eli Zaretskii; +Cc: rgm, 45143, rms On 2021-02-24, 17:13 +0200, Eli Zaretskii <eliz@gnu.org> wrote: >> From: Protesilaos Stavrou <info@protesilaos.com> >> Date: Wed, 24 Feb 2021 09:38:23 +0200 >> Cc: rgm@gnu.org, 45143@debbugs.gnu.org, Richard Stallman <rms@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-25 6:04 ` Protesilaos Stavrou @ 2021-02-25 14:40 ` Eli Zaretskii 2021-02-27 3:49 ` Glenn Morris 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-02-25 14:40 UTC (permalink / raw) To: Protesilaos Stavrou; +Cc: rgm, 45143, rms > From: Protesilaos Stavrou <info@protesilaos.com> > Cc: rgm@gnu.org, 45143@debbugs.gnu.org, rms@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.. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-25 14:40 ` Eli Zaretskii @ 2021-02-27 3:49 ` Glenn Morris 2021-02-27 3:55 ` Glenn Morris 2021-02-27 6:29 ` Protesilaos Stavrou 0 siblings, 2 replies; 32+ messages in thread From: Glenn Morris @ 2021-02-27 3:49 UTC (permalink / raw) To: 45143; +Cc: Protesilaos Stavrou, rms 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-27 3:49 ` Glenn Morris @ 2021-02-27 3:55 ` Glenn Morris 2021-02-27 6:29 ` Protesilaos Stavrou 1 sibling, 0 replies; 32+ messages in thread From: Glenn Morris @ 2021-02-27 3:55 UTC (permalink / raw) To: 45143; +Cc: Protesilaos Stavrou, rms 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-27 3:49 ` Glenn Morris 2021-02-27 3:55 ` Glenn Morris @ 2021-02-27 6:29 ` Protesilaos Stavrou 1 sibling, 0 replies; 32+ messages in thread From: Protesilaos Stavrou @ 2021-02-27 6:29 UTC (permalink / raw) To: Glenn Morris; +Cc: 45143, rms On 2021-02-26, 22:49 -0500, Glenn Morris <rgm@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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-21 6:15 ` bug#45143: Incorrect markup in some doc/misc manuals Richard Stallman 2021-02-21 11:01 ` Protesilaos Stavrou @ 2021-02-21 20:11 ` Eli Zaretskii 2021-02-24 6:49 ` Richard Stallman 1 sibling, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-02-21 20:11 UTC (permalink / raw) To: rms; +Cc: 45143 > From: Richard Stallman <rms@gnu.org> > Date: Sun, 21 Feb 2021 01:15:25 -0500 > Cc: 45143@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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-21 20:11 ` Eli Zaretskii @ 2021-02-24 6:49 ` Richard Stallman 2021-02-24 15:09 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Richard Stallman @ 2021-02-24 6:49 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 45143 [[[ 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) ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-24 6:49 ` Richard Stallman @ 2021-02-24 15:09 ` Eli Zaretskii 2021-02-26 6:32 ` Richard Stallman 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-02-24 15:09 UTC (permalink / raw) To: rms; +Cc: 45143 > From: Richard Stallman <rms@gnu.org> > Cc: 45143@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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-24 15:09 ` Eli Zaretskii @ 2021-02-26 6:32 ` Richard Stallman 2021-02-26 7:45 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Richard Stallman @ 2021-02-26 6:32 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 45143 [[[ 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) ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-26 6:32 ` Richard Stallman @ 2021-02-26 7:45 ` Eli Zaretskii 2021-02-27 16:14 ` Richard Stallman 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-02-26 7:45 UTC (permalink / raw) To: rms; +Cc: 45143 > From: Richard Stallman <rms@gnu.org> > Cc: 45143@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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-26 7:45 ` Eli Zaretskii @ 2021-02-27 16:14 ` Richard Stallman 2021-02-27 18:20 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Richard Stallman @ 2021-02-27 16:14 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 45143 [[[ 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) ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-27 16:14 ` Richard Stallman @ 2021-02-27 18:20 ` Eli Zaretskii 2021-03-01 5:18 ` Richard Stallman 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2021-02-27 18:20 UTC (permalink / raw) To: rms; +Cc: 45143 > From: Richard Stallman <rms@gnu.org> > Cc: 45143@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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* bug#45143: Incorrect markup in some doc/misc manuals 2021-02-27 18:20 ` Eli Zaretskii @ 2021-03-01 5:18 ` Richard Stallman 0 siblings, 0 replies; 32+ messages in thread From: Richard Stallman @ 2021-03-01 5:18 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 45143 [[[ 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) ^ permalink raw reply [flat|nested] 32+ messages in thread
end of thread, other threads:[~2021-03-01 5:18 UTC | newest] Thread overview: 32+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2020-12-09 17:41 bug#45143: Missing source for some doc/misc manuals? Glenn Morris 2020-12-15 18:17 ` Glenn Morris 2021-01-31 21:47 ` Glenn Morris 2021-02-17 5:40 ` bug#45143: Missing source for some doc/misc manuals (moral-issue) Glenn Morris 2021-02-17 8:45 ` Robert Pluim 2021-02-17 14:27 ` Basil L. Contovounesios 2021-02-17 14:41 ` Robert Pluim 2021-02-17 16:09 ` Eli Zaretskii 2021-02-17 16:15 ` Robert Pluim 2021-02-17 17:28 ` Eli Zaretskii 2021-02-19 5:34 ` Richard Stallman 2021-02-19 5:57 ` Glenn Morris 2021-02-21 6:15 ` Richard Stallman 2021-02-21 6:15 ` bug#45143: Incorrect markup in some doc/misc manuals Richard Stallman 2021-02-21 11:01 ` Protesilaos Stavrou 2021-02-22 6:22 ` Richard Stallman 2021-02-22 16:38 ` Protesilaos Stavrou 2021-02-24 7:38 ` Protesilaos Stavrou 2021-02-24 15:13 ` Eli Zaretskii 2021-02-25 6:04 ` Protesilaos Stavrou 2021-02-25 14:40 ` Eli Zaretskii 2021-02-27 3:49 ` Glenn Morris 2021-02-27 3:55 ` Glenn Morris 2021-02-27 6:29 ` Protesilaos Stavrou 2021-02-21 20:11 ` Eli Zaretskii 2021-02-24 6:49 ` Richard Stallman 2021-02-24 15:09 ` Eli Zaretskii 2021-02-26 6:32 ` Richard Stallman 2021-02-26 7:45 ` Eli Zaretskii 2021-02-27 16:14 ` Richard Stallman 2021-02-27 18:20 ` Eli Zaretskii 2021-03-01 5:18 ` Richard Stallman
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.