From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: =?utf-8?Q?K=C3=A9vin_Le_Gouguec?= Newsgroups: gmane.emacs.devel Subject: Re: Convert README.org to plain text README while installing package Date: Wed, 08 Jun 2022 00:15:32 +0200 Message-ID: <87pmjknmrf.fsf@gmail.com> References: <87leuca7v7.fsf@disroot.org> <87czfopmsd.fsf@gnu.org> <87h74ztshe.fsf@gmx.de> <871qw31ois.fsf@yahoo.com> <8735gj4ceo.fsf@gnu.org> <87ee038ipt.fsf@gmx.de> <87o7z61v59.fsf@gmail.com> <87bkv527p5.fsf@gmail.com> <87k09ttiad.fsf@yahoo.com> <87czflas36.fsf@gmail.com> <874k0wucxg.fsf@yahoo.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="40410"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: Tim Cross , Alan Mackenzie , emacs-devel@gnu.org To: Po Lu Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Jun 08 01:20:39 2022 Return-path: Envelope-to: ged-emacs-devel@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 1nyiV4-000AIF-SU for ged-emacs-devel@m.gmane-mx.org; Wed, 08 Jun 2022 01:20:38 +0200 Original-Received: from localhost ([::1]:54564 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nyiV3-0003uW-Ll for ged-emacs-devel@m.gmane-mx.org; Tue, 07 Jun 2022 19:20:37 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56910) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nyhU9-0006W1-D9 for emacs-devel@gnu.org; Tue, 07 Jun 2022 18:15:37 -0400 Original-Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]:43944) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nyhU7-0006Wk-NI for emacs-devel@gnu.org; Tue, 07 Jun 2022 18:15:37 -0400 Original-Received: by mail-wm1-x32e.google.com with SMTP id 67-20020a1c1946000000b00397382b44f4so10205354wmz.2 for ; Tue, 07 Jun 2022 15:15:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=5TTLEYUjIdcVA96yWUBoi+XjJ6c1k6jk1V/QIbAGGtE=; b=VQyg3iIrIqepGevRejpMce23kZJMgPUXkEK27YFf014sOhVsEMAqa7oWgMNGvMpQdR BFiAc8coFC/Y4SSzZovnCjjOcb/zBvfd+XncjhQkci7DE5IB9n6iFLAPZclqnwCc+A7H dz14UcKpDrh7rekhAonF854/TVN8glqAOOq0JTj1/7FvHJr8QiYF/2GDyjosgHcziANo RmFr0RZxp53x/jlClebVpnYf3yNI/SPI/OC/l7+ib2dbs36o5NHZjqs5wZuhLT5LzfpB 6ruQnnX54RyAOfTzKb8lhxJq2gP3u7wTGK9SEC/fyA+rUny2Z+c2/SBZd6Uky0qMYMkT pgXg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=5TTLEYUjIdcVA96yWUBoi+XjJ6c1k6jk1V/QIbAGGtE=; b=Hog6i2NMe6RsAEVpDXNkt4GkI9ZWSzZmlonXLVsTdv+/Su+a00FV+d8Q7MvofJKWGH ThYVEVOyC2A3hjathDl9lpySnsluFHi7znAJvI5uvMf0moXs18OvkActP3kcQ3On+orD oNMLBr1TsQVv0mIhY4uaqxq7WEUJa4jlfRYr7CRvShbUn4i76RjMXlRxTW0nm1en1rTX Oe5ulgLGGAmyiTppnkgpjnPP5CUoMxuKPGqwBBNP7trMpNFgLc74iKMrMq0z4RvKfAHV FXFQOzn8xD6pi7PIpliGRkg0CFuETsAWUJT4JBFMA+HkZSDmQLCraKloJJmpY4HfYJy4 iM4Q== X-Gm-Message-State: AOAM532t7p+aL5+xPmHq91qUryY/1B4CdnUKjKIxd/yD+kP37H9JDkdP sbImSf0Pdj5pjOQQKeHepcyDxobfrLI= X-Google-Smtp-Source: ABdhPJwo4k9YMEso4aQlj3nouvkDBDdCzs47a5+/RqGJN6an3uploCpfQ2OD5+mmYoOMsL/GF70AOg== X-Received: by 2002:a05:600c:3ac3:b0:399:323:3a8d with SMTP id d3-20020a05600c3ac300b0039903233a8dmr47208828wms.101.1654640133811; Tue, 07 Jun 2022 15:15:33 -0700 (PDT) Original-Received: from amdahl30 ([2a01:e0a:253:fe0:2ef0:5dff:fed2:7b49]) by smtp.gmail.com with ESMTPSA id f18-20020a5d4dd2000000b0020fd392df33sm19268409wru.29.2022.06.07.15.15.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 07 Jun 2022 15:15:33 -0700 (PDT) In-Reply-To: <874k0wucxg.fsf@yahoo.com> (Po Lu's message of "Tue, 07 Jun 2022 15:53:47 +0800") Received-SPF: pass client-ip=2a00:1450:4864:20::32e; envelope-from=kevin.legouguec@gmail.com; helo=mail-wm1-x32e.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:290888 Archived-At: Po Lu writes: > K=C3=A9vin Le Gouguec writes: > >> No one has ever had to "go through the entire Org manual in order to >> write and edit README files". Just like no one has ever had to read the >> Emacs manual cover-to-cover in order to do anything with it (they _can_, >> of course, but they don't _have to_). > > So what was the purpose of the following statement? > >>> Spend the time to go through the key bindings listed in the org >>> manual Cannot speak for Alan nor Tim, but my understanding of the exchange that led to the bit you quote is that Tim was inviting Alan to check how many of these 784 bindings had any relevance to the topic under discussion (navigating and, to a lesser extent, authoring Org READMEs) in order to show that "M-x org TAB" was not a good heuristic to assess how much complexity _needs_ to be shoved onto an unsuspecting README reader. In Tim's own words (a bit before the one you quote): > That 750 key bindings is an extreme over statement and not what is being > proposed. So your paraphrasing ("expecting someone to go through the entire Org manual in order to write and edit README files") struck me as disconnected from (my own understanding of) Tim's argument: AFAIU, * he wasn't saying _Org users_ need to go through the manual, * he was confronting the "784 bindings" argument by saying it was not a particularly useful heuristic, inviting _us_ (participants of the present discussion) to check for ourselves what proportion of these bindings are actually relevant to the discussion. Again though, cannot speak for Tim; I can only explain my undertanding of the discussion, and why I was dumbfounded by your reply. > IMO, packages should provide a plain text README, alongside a rich text > version in a relatively standard format like HTML. > > By using HTML, it becomes readable not only in Emacs, but also any other > program that understands HTML. HTML is also understood by many more > people than Org mode. > > It's okay for package maintainers to write their documentation using > Org, and then to export it to HTML. But please don't insist that all > documentation be written using Org mode, or that it's okay for packages > to only provide documentation in that format. If there's been advocating for all documentation to be written in Org, I've (dis)missed that, so sorry for not following closely enough. As for packages only providing documentation in Org: again, I think the way forward is automation at the package archive level. Asking authors to maintain two sync'ed READMEs stands a small chance of success IMO.