From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Karl Fogel Newsgroups: gmane.emacs.devel Subject: Improving documentation of Org Mode integration into Emacs. Date: Sat, 04 Dec 2021 15:14:59 -0600 Message-ID: <87zgpgax7w.fsf@red-bean.com> Reply-To: Karl Fogel Mime-Version: 1.0 Content-Type: text/plain; format=flowed Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="29814"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) To: Emacs Development Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Dec 04 22:16:11 2021 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 1mtcOA-0007Yy-Nc for ged-emacs-devel@m.gmane-mx.org; Sat, 04 Dec 2021 22:16:10 +0100 Original-Received: from localhost ([::1]:53670 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mtcO9-0001wD-JN for ged-emacs-devel@m.gmane-mx.org; Sat, 04 Dec 2021 16:16:09 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:40304) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mtcN7-00017u-RA for emacs-devel@gnu.org; Sat, 04 Dec 2021 16:15:06 -0500 Original-Received: from sanpietro.red-bean.com ([45.79.25.59]:53848) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mtcN5-0008S8-B8 for emacs-devel@gnu.org; Sat, 04 Dec 2021 16:15:05 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=red-bean.com; s=202005newsp; h=Content-Type:MIME-Version:Message-ID:Date: Reply-To:Subject:To:From:Sender:Cc:Content-Transfer-Encoding:Content-ID: Content-Description:In-Reply-To:References; bh=C1Vl8G8sZWBgb2Cu/XTvRfB5PpSGsqcfmEr+w1pIv8Y=; t=1638652500; x=1639862100; b=TMW7jzDq1nEtNdbP4eOaddsJ8XrXYDB6DlMhBu9J0djSMt065OMjVNtMrFuvxIy2Z21k/S5XjmB tlYafWrHvkcL6glPA8uNi1aFNMsKwkNO1npIKtYWhIXkS29EcqCxkQuSjFQIn7TEawcnpjzuehR4T swLFTlP4sjTtxnxAABc4terwuIoLo33MprwymE6/oTdJO0nLmreLbSEtZoR4u/6C4uwve8uIMCokb U01dByL7fa4cSpE6ci2d0m6uymO0F8/EVyQ0gLnyKn6jLCMWZg5gTiZEkf/zwbH8wkkrK1SjFP32i 9WpD6hj+z/DEKQr6FBl5pmtcc7QT3QAxJVmQ==; Original-Received: from 99-112-125-163.lightspeed.cicril.sbcglobal.net ([99.112.125.163]:60566 helo=floss) by sanpietro.red-bean.com with esmtpsa (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1mtcN1-009CWl-TC for emacs-devel@gnu.org; Sat, 04 Dec 2021 21:14:59 +0000 Received-SPF: pass client-ip=45.79.25.59; envelope-from=kfogel@red-bean.com; helo=sanpietro.red-bean.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, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 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:280945 Archived-At: I'd like to improve our in-tree documentation of how Org Mode integration into GNU Emacs works. Many of us know from experience that Org Mode is maintained in a separate repository at git://git.sv.gnu.org/emacs/org-mode.git, and that it has its own project home site at https://orgmode.org/. But to a newcomer or an occasional contributor, this isn't obvious: they just see the sources in 'lisp/org/', looking like any other Lisp subdir in Emacs. The fact that Org Mode is special is not clearly documented for those whose entry point is the Emacs sources. While "orgmode.org" is mentioned in a header comment in, e.g., 'org.el', it's not prominent, and it's especially easy to miss because one often lands in the middle of a .el file via etags or grep or some other method that doesn't involve entering through the top. And even for those who do happen to know that Org Mode is special, we can't tell from inspection exactly what 'lisp/org/' represents. Is it a release of Org Mode? A regularly-updated clone of the upstream development sources? Something else? I finally found https://orgmode.org/worg/org-maintenance.html#org9ffe058, which describes how it works. So I'd like to add some documentation in our tree, clarifying this situation for future searchers. Most likely, this would be a brief mention in CONTRIBUTE, pointing to a new file lisp/org/README which would give more details and point to the above page. Any objections / thoughts / suggestions about this, before I start on it? Best regards, -Karl [2] https://list.orgmode.org/87czmcccrp.fsf@red-bean.com/T/#u