From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id SJW8M8RrrGE6DwEAgWs5BA (envelope-from ) for ; Sun, 05 Dec 2021 08:35:32 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id yDNIL8RrrGE1KgAAbx9fmQ (envelope-from ) for ; Sun, 05 Dec 2021 07:35:32 +0000 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 4A586AEAB for ; Sun, 5 Dec 2021 08:35:32 +0100 (CET) Received: from localhost ([::1]:48338 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mtm3X-0000H9-FM for larch@yhetil.org; Sun, 05 Dec 2021 02:35:31 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52424) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mtm2P-0000F8-Jb for emacs-orgmode@gnu.org; Sun, 05 Dec 2021 02:34:21 -0500 Received: from [2607:f8b0:4864:20::1032] (port=50820 helo=mail-pj1-x1032.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mtm2N-0007jr-3R; Sun, 05 Dec 2021 02:34:21 -0500 Received: by mail-pj1-x1032.google.com with SMTP id x7so5464560pjn.0; Sat, 04 Dec 2021 23:34:18 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=GzQK5q05Eq84VXI6zbMVeh1NzctN6w3iwWsdk+91Rhg=; b=Mv5tjQn84LAypRS5IwsXmRckaBadJ3bX4Up2KnvA3zSVxw+ukgveIt9Plqx746k9Y3 cHihM1ynv9jgmGNybyZgc93lOKCXsyEAOLuINdIBcx1ShqwqLFf/maoZlk0XyhX/RzzG OVRPRIIaRQCLwPftuTveSG6Q/qcecjAgamSBkONZ3zp0AmV+3aYZYOjMmFRGIvoN8kYR 1g8I8Evx1SWkuvVtjxwUNPf/ZnQosYesz9HHJyuke4mA3nbdLEAAkmdkhYK5czXzjeQd rkSEU/1q3uDqgWLCzj3EaSi7RxaucLeb69PZHlDUba6ywsNoVRYMHdbpSngn3YJGokic /qRg== 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:date:message-id:mime-version :content-transfer-encoding; bh=GzQK5q05Eq84VXI6zbMVeh1NzctN6w3iwWsdk+91Rhg=; b=q8TlEKQPPTU/pWu5TFif3vZMCHcQ0WHfSUsnMRkTy/Ld/YEGX+5nbKhODzbOol2SJi FBcfY4sSK7qXcdEqsH4dExuzI8l+OXlOfx8/YpBqRUNnIWfO92ygWBQp23u0g4S4v/VM hEE1I4per4GxmJVGlZw5AhGnx4hI3iWE7j46DAn5xk6tQD+6IM6Lwi+vUhAW7w79UNGR 8Cf8gqPMkKvrY6Gt6dHg76cJRncaXc7O6MMvLPUf/PxzDD3mXQYP64AxQmHt88xa9FUo b6XnOi9ZWruFgWkZHF2btTsYeLLkfwdCebJ5lGVAP/tkWJOfls0k0iVw8YHOFGHkOi+t q90g== X-Gm-Message-State: AOAM530ud/sGXwsYpli1mKu+xX+zqxLzng7/PzidAd44J/pirrJzU5O4 y4mHyLzPi9XjG/CB/X9OCL/soGgSCWT17Za7 X-Google-Smtp-Source: ABdhPJzSxD9I40d71il7BbXQoP7XGjLj/1qT5KCtF05qNUNU35gZQWIOkANqypJzCGnZ782kE9drAQ== X-Received: by 2002:a17:902:f283:b0:141:f719:c434 with SMTP id k3-20020a170902f28300b00141f719c434mr34800042plc.79.1638689656939; Sat, 04 Dec 2021 23:34:16 -0800 (PST) Received: from localhost ([158.255.2.9]) by smtp.gmail.com with ESMTPSA id v25sm8334406pfg.175.2021.12.04.23.34.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 04 Dec 2021 23:34:16 -0800 (PST) From: Ihor Radchenko To: emacs-orgmode@gnu.org Subject: Concrete suggestions to improve Org mode third-party integration :: an afterthought following Karl Voit's Orgdown proposal Date: Sun, 05 Dec 2021 15:35:39 +0800 Message-ID: <87tufnbj1w.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Host-Lookup-Failed: Reverse DNS lookup failed for 2607:f8b0:4864:20::1032 (failed) Received-SPF: pass client-ip=2607:f8b0:4864:20::1032; envelope-from=yantar92@gmail.com; helo=mail-pj1-x1032.google.com X-Spam_score_int: -10 X-Spam_score: -1.1 X-Spam_bar: - X-Spam_report: (-1.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_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, PDS_HP_HELO_NORDNS=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RDNS_NONE=0.793, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no 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: , Cc: Karl Voit , Bastien , Timothy Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1638689732; 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:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=GzQK5q05Eq84VXI6zbMVeh1NzctN6w3iwWsdk+91Rhg=; b=UO+adP+4tInqkE3LaQrfLHthmUA3+oFs2tCPbUrtrc2viT7dT6yiV26t8GgPHgUY2OD+g2 rLk4hH1+m8A0ITmovcdVgRVmuWY+PMEaU0vmOoRbnltEPo/JLyi2rwkx2VmBZc4Dl0Bgxf WJ5/1icEuFYOUHrGW1Z3YFXF0rCAjjaKREe5+RkJ25iU+bLjyDhQLY6kKpdQ5RJ7+iqOUV bswMTHCaGLH4mpvdFK88zedamVW0ermZy49TA2nesyQjybYjYAp/9aFfLyAUv4RLHrOOw0 yPjLBSVKIzzCmEBxrjTCV+iuM25x5lcJ13a94WzoqVg4qkV2kkdFJ0OqoQd8lQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1638689732; a=rsa-sha256; cv=none; b=qTo6fnlG8cVdk++gs7Q9jjk0Huv1TU2Gdq814bAlfSeLSeEv2Fz5G3Cgcy5J6bxNZcTUbv R6MQMw2eCFL2rFTgZiv0t1btUKHkQJ/4EwlNRzaEy5JifF1OUfXaYCqp6+aMt4CCvpluyD XCxUJpif1vQ9ugvefZqd7GgZIZkxk3o3L1DOQP8gymaVNBXYAT5xBXj5IZYUb8q2OxatOb yoc13BlwuZlOxrEniN+HKiGq89vlnBG41vj3Hz83v5iVz2295qzfJc/7A0JVYkHGJVsxwV jit1xn8yoN1DDrYnPzatweiiKY2w2f0+gATwt7ztSriwCuuE8FJKfG7oq8N8CQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=Mv5tjQn8; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); 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" X-Migadu-Spam-Score: -1.33 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=Mv5tjQn8; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); 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" X-Migadu-Queue-Id: 4A586AEAB X-Spam-Score: -1.33 X-Migadu-Scanner: scn0.migadu.com X-TUID: BotJsFffnfc4 Dear Fellow Orgers, The recent spike of discussions following Karl's presentation in Emacsconf 2021 revealed a lot of controversy among Org and Emacs enthusiasts. Yet, Karl named a number of very real problems surrounding Org mode usage outside Emacs. >From the narrow perspective of this mailing list, I would like to list some of the problems and possible solutions to them on our (Org dev) side. 1. Org mode is almost impossible to separate from Emacs in its full strength - Yet, a number of people seems to be interested in using Org mode outside Emacs + Most notably, mobile users + A number of websites, like Github/Gitlab - The existing interest gave a rise to a number of third-party Org syntax parsers + None of the parsers support all the Org features, and even not all the grammar! + The parsers often do not even try to support all the features. They are merely looking at Org as a lightweight markup format. =20=20=20=20=20=20=20 2. Despite user interest, we lack a clear definition of Org grammar with examples and concrete guidelines for third-party parser developers 3. Many elements of the grammar are excessive for simple cases not involving document export, babel, and other powerful Org mode features 4. "Org mode" is an ambiguous word combination for search engines and people may not be able to find relevant information. - This one is not 100% true from my quick search. Try the following links: + https://duckduckgo.com/?q=3Dorg-mode&ia=3Dweb + https://duckduckgo.com/?q=3Dorg+mode&ia=3Dweb + https://duckduckgo.com/?q=3Dorg+mode+syntax&ia=3Dweb + https://duckduckgo.com/?q=3Dorg+mode+markup&ia=3Dweb The results are extremely relevant to Org, though orgmode.org search result looks slightly confusing (more below). =20=20=20=20=20=20=20=20=20=20 ------------------------------------------------------ | My suggestions how we can address the above points | ------------------------------------------------------ 1. Despite webengines delivering fairly good results for "Org mode" search term, I am a bit concerned about the first search hit, which is our flagship "https://orgmode.org" website. The website title is "Org mode for Emacs", repelling users who _do not want_ to use Org inside Emacs. Maybe we can do better? Something with less accent on Emacs like "Org mode: your life in plain text" The "abstract" in the search result is also not fully relevant: > Org and Org-mode have so many use cases that it is simply not > possible to easily document them, let alone show them all off on a > single page. As a result, Worg serves as a community wiki and > provides a place to document and share information about all aspects > of using and working with Org. For example, Worg contains: Again, we can make a simple change revealing the paragraph shown the at our front page: > Org is a highly flexible structured plain text file format, > composed of a few simple, yet versatile, structures =E2=80=94 construc= ted > to be both simple enough for the novice and powerful enough for the > expert.=20 >=20 > Org mode is also a GNU Emacs major mode for keeping notes, > authoring documents, computational notebooks, literate programming, > maintaining to-do lists, planning projects, and more =E2=80=94 in a fa= st > and effective plain text system. 2. Our front pages gives an impression that user must install Org I refer to the big image links "Features Install Quickstart Contribute" Maybe we can add "Try in browser" linking to our own instance of https://organice.200ok.ch/sample 3. We can provide a "source of truth" for Org syntax for third-party parser developers. Something easily reachable from the front page: "Org-Mode Logo Org Mode Features Releases ... --> Add Org support in third-party apps" The page should give a nice summary of existing third-party libraries, official _technical_ Org syntax, and tools for developers. 3.1. In particular, I suggest to link https://orgmode.org/worg/dev/org-syntax.html (it will be ready eventually) =20=20=20 3.2. Also, we may add a simplified Org syntax, as Karl suggested (similar to Basic and Extended syntax in https://www.markdownguide.org/, but more technical) =20=20=20 3.3. I strongly suggest to add a community test set with example Org files. The files should be a source of tests for Org parsers with the true parsed representations in sexp format (possibly also converted to json). The example files can live in a separate repo for easy contributions (possibly with Github/Gitlab mirrors is someone is willing to maintain those). The example files will be used by Org mode itself in our test suite and will serve as a benchmark for external parser quality. 3.4. Finally, we can have a separate page listing recommended features for editors interacting with Org files. Something like "implementation roadmap" (citing Timothy) for external devs. Again, unlike our existing feature page, this should be more technical and target developers. The features may include (we can add them as needed): - Folding / structural editing - Table editing / alignment - Source block execution - Babel - Export / publish - Setting TODO keywords - Agenda / searching in Org files - Clocking data - Capture - ... WDYT? Best, Ihor