From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:303:5f26::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms8.migadu.com with LMTPS id 6Ew+BbmSlGXVQgAAkFu2QA (envelope-from ) for ; Tue, 02 Jan 2024 23:48:25 +0100 Received: from aspmx1.migadu.com ([2001:41d0:303:e16b::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id QLtdAbmSlGUxsAAAqHPOHw (envelope-from ) for ; Tue, 02 Jan 2024 23:48:25 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=AAbvDvKk; 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=none; arc=pass ("zohomail.com:s=zohoarc:i=1") ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1704235705; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=QWVfvmA4fqfM6LkAn6X+/SGtprXLgTvXQlcL0XyFTno=; b=HfmDfQNoNoIa3KHsmwEflRBaAga/XZOzWoWdR40AYpnWRi3RpiShpiJdYO1ZoIxx3aTvZh xoTHuWMrp6dTS31ylG053KLpKKBCDW+dusY4ScIG9OJm+zAFLSqBMJPu/Ihu9NbCNJkqns YFOpFgIF1YwffBNt//YN78fcY19sKKNwMxHcSVZQiHtswW5bzOmnxiH4iNy7FZIp6EGF9R FBeI1ehg0TJa1YG+60cWCnRgy224/dQN/gYUW4ci4vltyX77yiC2BJddpJvsDy8WPmgiLm DkYUYKIDfC2DhMgyI91L0gLV0f/lF3oKSuTgotg1A91zqwtBqq2aCYlD7PT5fQ== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=AAbvDvKk; 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=none; arc=pass ("zohomail.com:s=zohoarc:i=1") ARC-Seal: i=2; s=key1; d=yhetil.org; t=1704235705; a=rsa-sha256; cv=pass; b=Wb9TA4sOTyF7c2ljrT4JL5EBwH6hZVE4PIZfLPgsZQbAGCvSkF1J02pIgbNd36roESon8c k7d4mC/Ae96DQ6Y7HWh7sBwIOx0Qd+/se3kVeZsT0QRQX/e8pmDD8xFSo3IhHaBycyj6fY 2cE/kh8S5ZtkwPODDdKC9fKVRmMol7cL+Od2AXCRFm0XNFbqRJKM191ZIk9WDSwfliD+Wr lZkuZ31XZgsb3vNohnFOwx6QmTZRsP0xUXwwC9lYYZRzAbtf2roagbzaHDjQj/cpQp4aoy mhJJUedhsDrUfg4Ku88j+XlPziLsii/hGDNtCiIuLkE23R3bueqz4Yk4MIpXiw== 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 71E6A1745C for ; Tue, 2 Jan 2024 23:48:24 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rKnXn-0002qg-1I; Tue, 02 Jan 2024 17:47:31 -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 1rKnXl-0002qH-9j for emacs-orgmode@gnu.org; Tue, 02 Jan 2024 17:47:29 -0500 Received: from sender4-op-o15.zoho.com ([136.143.188.15]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rKnXh-000122-Oz; Tue, 02 Jan 2024 17:47:27 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1704235641; cv=none; d=zohomail.com; s=zohoarc; b=PTMnT0K7ZP+bOvQwmdObosch5L2dsD1nY4/TIBSou2EEkRzpedwbyL9aUGs+XImcxC/M8tI4EHtrfHS+c4h+dIR9zT4m9h19wHFRiW5YnjxrtOeiW2O2Ypr9waBHH1RGJTkqiFJfXde/CH0oVNEghkZnbsYu5+XPKZ9yeYhD7j8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1704235641; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:Subject:To:To:Message-Id:Reply-To; bh=QWVfvmA4fqfM6LkAn6X+/SGtprXLgTvXQlcL0XyFTno=; b=DRpUml9RNdFPKdn6frJHNnjAO3RdKSSVHogUrOoXUZJ1zXsrtQz4CRwGNUncHuM4Ke8X9r6FoKiyvM3ZCSb3DDT8YjrByYbKJuZOl+udLcfqj/VL1EXuHO8SMTNX70DHMaAKOdn7+ba514CSIy7KUo756EShB/A3N94y+eYmrT0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=excalamus.com; spf=pass smtp.mailfrom=matt@excalamus.com; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1704235641; s=zmail; d=excalamus.com; i=matt@excalamus.com; h=Date:Date:From:From:To:To:Cc:Cc:Message-ID:In-Reply-To:References:Subject:Subject:MIME-Version:Content-Type:Content-Transfer-Encoding:Message-Id:Reply-To; bh=QWVfvmA4fqfM6LkAn6X+/SGtprXLgTvXQlcL0XyFTno=; b=AAbvDvKk1tn5HMC7Ld2QLH0sRH1TzVonT77FhiXoYRPEAr0iMin30cWEtiloPUtU B8lQ9JXUdZjwiSXyLtd7Pbb/DO+guv56u9NkMvDEyG9g1i0GusC5yWPMQdUDdVfF4sD r/SNy6kNPNwbb8dCai+QK1M+GimenJnGJgsz45LQ= Received: from mail.zoho.com by mx.zohomail.com with SMTP id 1704235640003440.34075503963004; Tue, 2 Jan 2024 14:47:20 -0800 (PST) Date: Tue, 02 Jan 2024 23:47:19 +0100 From: Matt To: "Ihor Radchenko" Cc: "emacs-orgmode" , "Bastien" Message-ID: <18ccc5c24ab.11c0534ea910085.7925872212667260908@excalamus.com> In-Reply-To: <87il4e75u8.fsf@localhost> References: <87il4e75u8.fsf@localhost> Subject: Re: [PATCH] doc/org-manual.org (Summary): Clarify the Org markup is human-readable MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Importance: Medium User-Agent: Zoho Mail X-Mailer: Zoho Mail Received-SPF: pass client-ip=136.143.188.15; envelope-from=matt@excalamus.com; helo=sender4-op-o15.zoho.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, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-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-Scanner: mx13.migadu.com X-Migadu-Spam-Score: -7.95 X-Spam-Score: -7.95 X-Migadu-Queue-Id: 71E6A1745C X-TUID: zVVgpmONxvm4 ---- On Sun, 31 Dec 2023 16:22:00 +0100 Ihor Radchenko wrote --- > > I'd like to amend the Org manual introduction as in the attached patch. > The idea is to highlight that Org markup is designed to be > human-readable first and foremost rather than just computer-readable. > > This is the first section of the manual. Most of the new users will see > it. So, I'd like to hear any objections before installing the patch. I like the points about using any text editor and understanding Org without an editor. The main point, it seems, is Org mode avoids lock-in. Two perspectives, the author and the reader, are addressed. An important question is, "Who are we writing to?" Addressing authors and readers covers pretty much everyone, I think :) I believe that makes these good points for the intro. The first paragraph of the current introduction reads, "Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. It relies on a lightweight plain-text markup language used in files with the =3D.org=3D extension." Since the first paragraph already mentions "lightweight plain-text markup language," I think making a similar point in the next paragraph is unnecessary. It may be better to say what you want in the first paragraph. I like "human-readable." It's clear and direct. However, trying to incorporate it into the first paragraph becomes heavy: "Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. It relies on a human-readable, plain-text markup language used in files with the =3D.org=3D extension." That's a lot of hyphenated words and syllables! Maybe "legible" would be better? It's more precise. But maybe precise isn't good. I'm wondering if there's a simpler word that accommodates non-native speakers better (and not just for this word). "Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. It relies on a legible, plain-text markup language used in files with the =3D.org=3D extension." Last comment on your changes. I understand what you mean by "with a naked eye" and I think it's a valid point. However, not everyone who uses Emacs can see. I wonder, do the benefits of Org syntax only apply visually? 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. 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. 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. 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). Text encodings notwithstanding (plain-text is only as portable as far as you can guess the encoding), what do you think of something like this? modified doc/org-manual.org @@ -18,9 +18,10 @@ :END: #+cindex: summary -Org Mode is an authoring tool and a TODO lists manager for GNU Emacs. -It relies on a lightweight plain-text markup language used in files -with the =3D.org=3D extension. +Org Mode is an authoring tool and a to-do lists manager for GNU Emacs. +It uses a legible plain-text notation to show formatting, structure, +relationships. Anyone able to edit text can write using Org. Anyone +able to read text can view it. As an authoring tool, Org helps you write structured documents and provides exporting facilities. Org files can also be used for literate -- Matt Trzcinski Emacs Org contributor (ob-shell) Learn more about Org mode at https://orgmode.org Support Org development at=C2=A0https://liberapay.com/org-mode