From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Protesilaos Stavrou Newsgroups: gmane.emacs.bugs Subject: bug#45143: Incorrect markup in some doc/misc manuals Date: Wed, 24 Feb 2021 09:38:23 +0200 Message-ID: <877dmxrk40.fsf@protesilaos.com> References: <3y4kku7u8d.fsf@fencepost.gnu.org> <3pft2gpyn5.fsf@fencepost.gnu.org> <0nmtw32qvz.fsf_-_@fencepost.gnu.org> <87lfbhsmzp.fsf@protesilaos.com> <87zgzwjbvk.fsf@protesilaos.com> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34364"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: rgm@gnu.org, 45143@debbugs.gnu.org, Richard Stallman To: Protesilaos Stavrou Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Feb 24 08:41:06 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1lEonB-0008pW-Uc for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 24 Feb 2021 08:41:06 +0100 Original-Received: from localhost ([::1]:54304 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lEonA-0006ha-R9 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 24 Feb 2021 02:41:04 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:55562) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lEolD-0005iR-Jr for bug-gnu-emacs@gnu.org; Wed, 24 Feb 2021 02:39:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:49867) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lEolC-00006T-Bo for bug-gnu-emacs@gnu.org; Wed, 24 Feb 2021 02:39:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lEolC-0007aK-9h for bug-gnu-emacs@gnu.org; Wed, 24 Feb 2021 02:39:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Protesilaos Stavrou Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 24 Feb 2021 07:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 45143 X-GNU-PR-Package: emacs Original-Received: via spool by 45143-submit@debbugs.gnu.org id=B45143.161415231929127 (code B ref 45143); Wed, 24 Feb 2021 07:39:02 +0000 Original-Received: (at 45143) by debbugs.gnu.org; 24 Feb 2021 07:38:39 +0000 Original-Received: from localhost ([127.0.0.1]:33180 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lEokl-0007Zf-4U for submit@debbugs.gnu.org; Wed, 24 Feb 2021 02:38:39 -0500 Original-Received: from relay9-d.mail.gandi.net ([217.70.183.199]:47479) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lEokj-0007ZR-4V for 45143@debbugs.gnu.org; Wed, 24 Feb 2021 02:38:33 -0500 X-Originating-IP: 94.46.225.161 Original-Received: from kronos (unknown [94.46.225.161]) (Authenticated sender: public@protesilaos.com) by relay9-d.mail.gandi.net (Postfix) with ESMTPSA id 1A539FF80E; Wed, 24 Feb 2021 07:38:25 +0000 (UTC) In-Reply-To: <87zgzwjbvk.fsf@protesilaos.com> (Protesilaos Stavrou's message of "Mon, 22 Feb 2021 18:38:55 +0200") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:200705 Archived-At: 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]: . [2]: . On 2021-02-22, 18:38 +0200, Protesilaos Stavrou wrote: > On 2021-02-22, 01:22 -0500, Richard Stallman 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]: . -- Protesilaos Stavrou protesilaos.com