From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:1008:1e59::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms8.migadu.com with LMTPS id GLl+BRxklWU1UQEAkFu2QA (envelope-from ) for ; Wed, 03 Jan 2024 14:41:48 +0100 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id yEkRABxklWXZqQAA62LTzQ (envelope-from ) for ; Wed, 03 Jan 2024 14:41:48 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=OFY7esJm; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=posteo.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1704289307; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=+SaaOYIrDBZX+CLwUd/I7q4vAHZYfWAKDeR5tAKAap4=; b=pubzp34OjjaxX8wvzUv438FgCca5gn22Qh/Mcwz45SGJUFNZHeOJu7FKdnb0axC4sfXIZt t/YASLE8pUYSlw+ZHa1Dt77P8GIQbzGPz3qfqoO/eNM9zRBxHEQ+QwxhnEp4mgvuweu5nT yb1WuqZRFD6USYmlFVO34Zd/4dXg7tlJ0IGuLERReu9FI4KZe+sBA4mNSM8qmxgFuJSKIy n8izhGErYtDrLPlVepJ+bwh5Y1gJD8j9z2ZmbvKYppnPVbcQVcEMA4ygo9BG1fw8lvTY3b zLaXrjZ3WWKbOQY0+JLE0gx/4Abn0jDTKewkIO9XnVwI56/gaZY/nHaimg7cUQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=OFY7esJm; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=posteo.net ARC-Seal: i=1; s=key1; d=yhetil.org; t=1704289307; a=rsa-sha256; cv=none; b=erUe5NljS72qjkCDbZXFWXux9j3H+SRpUImsATLc9tWMPqxmlPvAS7bceNcHuJmqhKztax GoEvnfgkgFgxvXKluvyg+UL0xGJvbvVWBAm0ZNmJJd5YcNOCBOkDh9vc+PfWK9UORVFK7h NooZCo9U+fhTS7bq4ujGWRpJxjQd4Kos9R0BKnV9G4G0Sp47lcyVwtOai44GKNW5cBgrvZ 1oAbNbDqVAp4liFkXYfBELh/o+wS+t8Rj7DDWgflW3oMh3nHpZsiD/4IejBDpCQN7mIZuD j/YiWs1A47eFSY7+dp+/Dy9DoqkyaLMlEIE/wD0CQkC/COrUgaH6W02Mj6JwFQ== Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id AA71960093 for ; Wed, 3 Jan 2024 14:41:47 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rL1UO-0004TP-0S; Wed, 03 Jan 2024 08:40:56 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rL1UL-0004TG-Sj for emacs-orgmode@gnu.org; Wed, 03 Jan 2024 08:40:53 -0500 Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rL1UJ-0004RH-F6 for emacs-orgmode@gnu.org; Wed, 03 Jan 2024 08:40:53 -0500 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 15B8024002D for ; Wed, 3 Jan 2024 14:40:48 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1704289249; bh=Y/+hOL++OQpdDmAdO3xQ9hbiGqpUxXJ3HfSe0E7zUo4=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:From; b=OFY7esJmCDX4LByNLV/Cir4JQk0sgiZ71wYuomp5q+elzvVFzOYF+jidjj2TdURaF GMyprgW+69WBLMWMWlbmCuYc0qLLf3bVuWdpfV2I6GjIt9Bx1mngoNtGnOaXeVd3jy BYQotlamzF9juMK12xgJc7j3vTgmXwN8/Q5AEqSKiVU6zl4UI2FBNhvYYj/vIxIvbJ 9fCbXBx+XJ7oRFgmMBQB9Fl8kQCnkpNCi/ZNSS9d9acpNk2z0uDllJ1SSYSK1AlNnx Wa62WbJcF6RMQ6E6qtYt+2tOBBDMvmjRdnUV2IIdZl1vaPWPs3z9FDSfGqTycrk5Zu KTMfwAaUvk2uQ== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4T4rTD0crJz9rxD; Wed, 3 Jan 2024 14:40:47 +0100 (CET) From: Ihor Radchenko To: Matt Cc: emacs-orgmode , Bastien Subject: Comments on Summary section of Org manual (was: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable) In-Reply-To: <18ccc5c24ab.11c0534ea910085.7925872212667260908@excalamus.com> References: <87il4e75u8.fsf@localhost> <18ccc5c24ab.11c0534ea910085.7925872212667260908@excalamus.com> Date: Wed, 03 Jan 2024 13:44:00 +0000 Message-ID: <87o7e2a5wf.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=185.67.36.65; envelope-from=yantar92@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 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, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: -9.49 X-Spam-Score: -9.49 X-Migadu-Queue-Id: AA71960093 X-Migadu-Scanner: mx10.migadu.com X-TUID: 0UWmgWpTn1Vf Matt writes: > Several things in the first paragraph unrelated to your changes stick > out to me. I can't help but make some other remarks. > > "TODO" should probably be "to-do". Every dictionary I looked in has > an entry for "to-do". I think that's the common spelling. Yet, we consistently use TODO keyword and TODO list across the whole manual. Stackexchange tells that both variants are valid: https://english.stackexchange.com/questions/46217/todo-list-or-to-do-list although "todo" is much less widely used. I do not see much benefit changing "todo list" to "to-do list". Both are clear and both are grammatically correct. > Regarding "markup language," that reads to me like programmer jargon. > What does it mean and why should someone care? Again, who are we > writing to? A markup language is a notation for formatting, > structure, and relationships. I think it would be best to directly > say that. What about "plain text file format"? > I would also soften that Org "relies" on its markup. It doesn't. I > used Org only for lists for a long time. I believe lists to be a > fundamental feature of Org (and hence a great item for the first > sentence). Lists are as simple as dashes. It's hard to say that > dashes before list items is a markup language. Yet, it is. You cannot, for example, use "." as bullets in Org mode. Also, indentation matters in Org lists, while it does not matter in more free-style writing. > Finally, I don't think the file extension is relevant for the first > paragraph. Technically, an extension isn't necessary. A person can > call M-x org-mode or use a file local variable. Worse, I think the > extension contradicts the point that any text editor can view an Org > file. Ever try to open a .org file in Windows? It asks for the > program. Yes, *technically* Windows could open a .org file *if* the > person opening it knew which program to use (or to change the > extension to something like .txt). Again, who are we writing to? If > it's someone who believes file extensions matter, then this would > introduce unnecessary friction. It seems best to avoid it. Better to > do as you've done and say Org is readable (which it is) rather than > specify the extension (which doesn't really matter). I am mostly neutral here, but I can see an argument why mentioning .org extension may be useful - unlike Windows, GitHub does expect .org file extension specifically to render Org mode files. The same goes for non-Emacs editors that support Org markup. For example, Vim/Neovim. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at