emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Ihor Radchenko <yantar92@gmail.com>
To: emacs-orgmode@gnu.org
Cc: Karl Voit <devnull@Karl-Voit.at>, Bastien <bzg@gnu.org>,
	Timothy <tecosaur@gmail.com>
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	[thread overview]
Message-ID: <87tufnbj1w.fsf@localhost> (raw)

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.
       
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=org-mode&ia=web
     + https://duckduckgo.com/?q=org+mode&ia=web
     + https://duckduckgo.com/?q=org+mode+syntax&ia=web
     + https://duckduckgo.com/?q=org+mode+markup&ia=web
     The results are extremely relevant to Org, though orgmode.org
     search result looks slightly confusing (more below).
          
------------------------------------------------------
| 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 — constructed
   > to be both simple enough for the novice and powerful enough for the
   > expert. 
   > 
   > 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 — in a fast
   > 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)
   
   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)
   
   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


             reply	other threads:[~2021-12-05  7:35 UTC|newest]

Thread overview: 59+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-12-05  7:35 Ihor Radchenko [this message]
2021-12-05  9:16 ` Concrete suggestions to improve Org mode third-party integration :: an afterthought following Karl Voit's Orgdown proposal Juan Manuel Macías
2021-12-05 10:24   ` Ihor Radchenko
2021-12-05 11:08     ` Juan Manuel Macías
2021-12-05 11:54       ` Heinz Tuechler
2021-12-05 12:08       ` Ihor Radchenko
2021-12-05 13:32         ` Tim Cross
2021-12-05 13:52           ` Bruce D'Arcus
2021-12-05 22:20             ` Tim Cross
2021-12-05 14:30           ` Ihor Radchenko
2021-12-05 22:39             ` Tim Cross
2021-12-08 13:47               ` Ihor Radchenko
2021-12-08 14:39                 ` Tim Cross
2021-12-08 16:16                   ` Dr. Arne Babenhauserheide
2021-12-08 17:07                     ` Russell Adams
2021-12-08 19:22                       ` Dr. Arne Babenhauserheide
2021-12-08 20:14                         ` Russell Adams
2021-12-08 21:50                           ` Tim Cross
2021-12-09  8:12                             ` Dr. Arne Babenhauserheide
2021-12-08 21:25                         ` Tim Cross
2021-12-09  8:07                           ` Dr. Arne Babenhauserheide
2021-12-09  8:36                             ` Timothy
2021-12-09  9:18                               ` Ihor Radchenko
2021-12-09 10:46                     ` Eric S Fraga
2021-12-09 15:21                       ` Russell Adams
2021-12-09 16:25                         ` Eric S Fraga
2021-12-09 21:15                           ` Samuel Wales
2021-12-09 23:27                         ` Dr. Arne Babenhauserheide
2021-12-10  2:42                           ` Tim Cross
2021-12-10  6:08                             ` Dr. Arne Babenhauserheide
2021-12-11 10:03                   ` Ihor Radchenko
2021-12-11 21:19                     ` Tim Cross
2021-12-06 19:41             ` Karl Voit
2021-12-05 18:59         ` Juan Manuel Macías
2021-12-05 23:24           ` Russell Adams
2021-12-06  5:57             ` Juan Manuel Macías
2021-12-06  6:02               ` Timothy
2021-12-06  7:24                 ` Juan Manuel Macías
2021-12-06 10:04                   ` Greg Minshall
2021-12-06 14:59                     ` Juan Manuel Macías
2021-12-06 17:59                       ` Tom Gillespie
2021-12-06 18:25                         ` M. ‘quintus’ Gülker
2021-12-06 18:42                           ` Russell Adams
2021-12-06 18:47                             ` Timothy
2021-12-06 19:28                               ` Russell Adams
2021-12-06 19:34                                 ` Timothy
2021-12-06 18:30                         ` Russell Adams
2021-12-06 19:10                         ` Gerry Agbobada
2021-12-08 12:56                           ` Ihor Radchenko
2021-12-06 10:08         ` Greg Minshall
2021-12-06 19:45         ` Karl Voit
2021-12-07 11:08           ` Vincent Breton
2021-12-08 13:13             ` Ihor Radchenko
2021-12-08 13:30           ` Ihor Radchenko
2021-12-05 13:06   ` Tim Cross
2021-12-05 14:55     ` Ihor Radchenko
2021-12-05 18:54 ` Timothy
2021-12-06 11:08 ` Max Nikulin
2021-12-06 18:43 ` Russell Adams

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87tufnbj1w.fsf@localhost \
    --to=yantar92@gmail.com \
    --cc=bzg@gnu.org \
    --cc=devnull@Karl-Voit.at \
    --cc=emacs-orgmode@gnu.org \
    --cc=tecosaur@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).