Back to the schedule
Previous: Org as an executable format
Next: Using Org-mode to teach programming

The use of Org mode syntax outside of GNU/Emacs

Karl Voit

CategoryOrgMode

Q&A: live Q&A or IRC
Duration: 12:09

If you have questions and the speaker has not indicated public contact information on this page, please feel free to e-mail us at emacsconf-submit@gnu.org and we'll forward your question to the speaker.

Talk

Download video, 12:09, 27.1M

Download --main.vtt
View on Toobnix

Q&A

Download video, 27:32, 64.9M

Description

With the rising interest in Org mode, the GNU/Emacs community gained much momentum in the last decade. Being a nicely designed lightweight markup language, Org mode does not only benefit users of GNU/Emacs. There are many tools and services supporting Org mode syntax documents that do have no direct connection to GNU/Emacs. I would like to elaborate on the advantages on using Org mode syntax for arbitrary text outside of GNU/Emacs for better typing usability and collaboration tasks.

Unfortunately, we do face some issues with the current situation. First of all, we do already have a number of non-Emacs tools that do support Org mode syntax. Then, we also do have an unclear consensus of what it takes to "support Org mode" without re-implementing the whole feature-set of Org mode of GNU/Emacs.

For that purpose, I came up with a new name for the syntax of the Org mode lightweight markup language: Orgdown.

Please do visit the Orgdown homepage and read my motivation article Orgdown - a New Lightweight Markup Standard for Text Documents for further information.

Discussion

Pad:

BBB:

  • Hi Karl. I was wondering, does the specification make any restrictions with regard to indentation levels or hard vs. soft line breaks? Do you have any type of test suites that an implementation can use to be "certified" as orgdown(1)?
  • Are you worried about the different levels of orgdown leading to the same confusing situation we have with Markdown?
  • I think the ability to indicate that some tools are compatible with org is fantastic!
  • Less of a question and more of an idea: I feel like it might be clearer to have more "semantic" names for orgdown such as "basic" orgdown, "full" orgdown or something. Those names are not great, but I think that might make it easier to remember what is what. Thoughts? Was there a specific reason for choosing a numbering system?
    • I like the Idea very much. There are some Mobile Markdown/Text Editors which shy away from support for org-mode. Maybe with orgdown support will be more widespread.
    • Questioner: And we should really try to proliferate the orgdown compatibily
  • Was the syntax specification based on commonmark in any way?
  • I think my main concern when writing in org mode at the moment is that exporters aren't heavily test (I found the plain text export was accidentally mixing spaces and tabs in indentation). Do you have any thoughts on a specification of reference implementation for an export process? Or is that out-of-scope?
  • although usb 3.2 2x2 is also not much clearer
  • Oh, tags are not included in orgdown1 ... would this come in 2, or is there some workaround?
  • I like the Idea very much. There are some Mobile Markdown/Text Editors which shy away from support for org-mode. Maybe with orgdown support will be more widespread. I did actually plan on making an org-roam focused app, for which I will definitely include the orgdown compatibility! Very excited about this
    • You already answered this (tags). Sounds good to keep it simple at first.
  • On the gitlab page it mentions that GH/GL have 95% support for orgdown: what is the 5 missing percent?
  • Are you hoping for most of this discussion to happen through GitLab?
  • Shame that gitlab does not have a github like discussion page yet
  • Did you get any feedback from the Org mode maintainers?
  • Just wanna preface this that I don't wanna complain about GitLab. Just also bringing up what a few folks on #emacsconf said as well. Sourcehut could be used, especially because of its mailing lists feature. The only other reason I could see that being interesting is that the head of Sourcehut is a large Gemini advocate as well. That could motivate more attention within the growing Gemini community for using Orgdown (outside of Emacs).
  • Yeah, honestly, I'm excited to see what the rest of the Org community would want. Whatever platform, I'm excited to start contributing when I can.
  • There seems to be a similar simplify-the-org-format approach in this recent neovim project: https://github.com/nvim-neorg/neorg, FYI. Might be worth looking to see if orgdown1 is compatible
  • neorg seems to be an expanded org-mode syntax and is not compatible with orgmode

BBB feedback:

  • I think no tags is a good idea, very implementation specific
  • I think it's a fantastic idea, and the initial proposal is very good!
  • i need to go, but thanks for introducing the idea, excited to see where it goes!
  • Thanks for your proposal. I really hope it will work out.

IRC: (nick: publicvoit)

  • is there a tree-sitter parser for orgdown already? :P
  • it seems to me that as org evolves, either orgdown eventually becomes incompatible with org or org is prevented from changing because it would break orgdown. I guess backcompat with existing org documents constrains org-mode this way already, though
  • what level would you call github's implementation is?
  • i'm not sure if we want a proliferation of org-syntaxes like markdown's
  • Disentangling "org" the markup language and "org"/"org-mode" the piece of software that runs inside Emacs is long overdue
  • I gotta say, why "Orgdown" and not just "Org"? That way we've got "Org" (the markup syntax) and "Org-Mode", the mode for that. Just delineate the mode from the thing the mode handles.
    • there was a move in the opposite direction, using "Org" instead of "Org-mode" for the piece of software that runs inside Emacs, which to me is where the problem arises...
  • +1 for "org" aas the format name, and the (already present) derived handling of the format being org-mode! To be clear, +1000000% in favour of this generally.
  • Next year. Talk on presenting org as a mime-type. Who?
    • it's officially being considered as a 'thing to be done or at least talked about', but I don't have a better status than that.
  • I think the org/orgdown split makes sense: orgdown stripped-down org
  • Why GitLab? GitLab.com requires reCAPTCHA to sign up, and nonfree cloudflare js to sign in
    • publicvoit: I wanted to test an alternative to GitHub which I was using so far.
      • I recommend codeberg.org, notabug.org, sr.ht, or savannah.nongnu.org
  • already uses the ".org.txt" file extension, so that tools that don't otherwise support the org file type will at the very least read them
  • sorry to have missed out on the discussion during your talk, but I'm extremely interested in getting org working outside elisp (re: https://github.com/tgbugs/laundry/tree/next). I started there long ago, at this point the issues that really need standardization is org-babel, but in order to do that we need the syntax settled, which has turned out to be a lot of work
  • having orgdown as a way to talk about files that have org syntax seems like it is a critical piece for effective outreach
  • would it be worth considering a decoupling of the "orgdown" proposal into 1) just a proposal to rename "org" the markup as "orgdown" (vs "org-mode" for the piece of software running in Emacs), and 2) all the rest as in the levels/etc? Just to not put the first at risk of non-adoption because of the contents of the second? There seems to be a lot of positive sentiment towards solving #1 for sure.
    • orgdown is not org, the markup
    • orgdown is lightweight org, it does not have all the features
    • In general I agree, there will be issues with how to approach the levels
    • publicvoit: Valid approach but this train has left the station already by the decision of myself to provide OD1 to the public this weekend.
  • To be fair, I personally don't think adding tiers to org-mode makes much sense
    • We should rather have a feature matrix for stuff like pandoc to check against
    • developing the test suite will get us there, and then we can have the discussion about how to market the levels
  • I think we could adopt orgdown almost immediately without issue
  • I don't really see a big issue with org-mode vs. org vs. orgWHATEVER though
    • there are major search and discovery issues with bare "org"
    • I tend to use "org syntax" at the moment, but it isn't catchy enough

From YouTube:

  • Great idea! I’m not sure about the name though. To me it implies it has something syntactically to do with Markdown (which it doesn’t). In my view OrgMode markup is far more expressive than Markdown. It’s almost a new markup language in and of itself. So, how about OrgMark or Org Mode Markup Language aka OMML.

Links and other notes:

Outline

  • The term Org mode stands for different things
  • The Org syntax is better than much more dominant lightweight markup languages
  • We do have an unclear consensus of "Org mode support"
  • A new name for the syntax alone: Orgdown
  • What Orgdown should be and should not be
  • Advantages of Orgdown for everybody
  • Orgdown comes in different levels: Orgdown1
  • OD1 Compatibility Percentage
  • The future of Orgdown
  • Your contribution!

Personal information

  • Name pronunciation: sounds like "karl foit" (IPA: kaʁl foɪt)
  • Pronouns: he/him
  • Homepage: https://Karl-Voit.at
  • Preferred contact info: EmacsConf21 (ɶt) Karl-Voit.at

Transcript

Hello. My name is Karl Voit, and I've spent the last decade working with Emacs Org Mode as my main organization system for my use cases, and I would like to take this opportunity and point out a subtle issue we've had in many different discussions around Org Mode, which itself stands for quite different kind of things. On the one hand side, Org Mode is an implementation in Elisp on the Emacs platform, and on the other hand side, Org Mode is also a lightweight markup language which we use to express things: how headings are marked, how text is made boldface, how external links are written, and so forth, in text documents.

[00:01:01.920] From my own experience, from many different online discussions, I once wrote a blog article on my web page that summarizes why I do think that Org Mode is superior to other well-known lightweight markup languages such as Markdown, AsciiDoc, reStructuredText and more. My main points in this article were that Org Mode is an intuitive and easy to learn and remember markup. It is standardized, as in the Emacs implementation defines the current standard, and there is no different Org mode version out there which conflicts with that. Org Mode is consistent within its markup language design. Org Mode can be easily typed in any text-based tool, and Org Mode makes much sense outside of Emacs, so that you can use it, for example, in email clients or in other text documents not interpreting the markup at all. And of course, if you want, you can have the perfect tool support within Emacs and other software tools.

[00:02:13.760] This naming issue, using one name for two different kind of things, arises in discussions about the markup's support in non-Emacs tools and services, in questions on levels of compatibility in comparison to the large and huge amount of functionality within Emacs, and so forth.

[00:02:36.319] In order to find a solution to some of those issues, I propose a different name. A new idea. A definition for the lightweight markup language, and the lightweight markup language alone. A new standard, which, by the way, reminds me on something here... Anyway... So we need a different name for this new thing, and its feature set needs to be something good enough to help adapting Org Mode syntax outside of the Emacs universe. It can't be the whole set of Org Mode features. This would kill the idea instantly, because everything that is going into that direction would be compared to our golden standards, the Emacs implementation of Org Mode, which cannot be compared to anything else at this time. So it needs to be somehow less than Org Mode. It needs to be recognizable in non-Emacs circles, and it should remind people on similar things in order to be something somewhat self-explanatory as a term. Hereby, I propose the name Orgdown for this thing, and it's launched with my Emacs Conference talk 2021.

[00:04:06.239] So what should Orgdown be? It should be a subset of Org Mode lightweight markup language syntax. It should be a definition of Org-Mode-based entities that do make sense on their own which is, in any case, always a compromise of some sort, of course. It needs to be extensible for different purposes to ensure future-proofness, and it needs to have a formal definition of Org Mode, which helps in becoming a new standard. it needs to be a self-sustaining community that supports the process by documentation and connecting people to other people, to the documentation, and to tools. What Orgdown should never be is something that's incompatible with Org Mode within Emacs, and some kind of Org Mode replacement, of course.

[00:05:08.560] The advantages of Orgdown for everybody includes better Org support in non-Emacs tools; to promote the beautifully crafted Org Mode syntax to a larger set of people, even outside of Emacs, of course; to push better support for the collaboration for Emacs and non-Emacs users for using text-based documents; finally, fix the irritating mix-up of markup language support and its Elisp implementation.

[00:05:41.680] I already mentioned briefly the need for a definition and extensibility. Therefore I came up with the idea of having different levels of Orgdown, and the first and most basic level of Orgdown is called Orgdown1. Orgdown1, or in short, OD1, consists of a small set of Org-Mode-based features such as simple text formatting, headings, lists, and checkboxes, example, quote, and source blocks, comments, external web links, tables without calculations. I tried to find a compromise that should work with most people starting with any lightweight markup that is based on Emacs Org Mode. In order to get a measure on how well Orgdown1 is supported by one specific tool, I came up with an OD1 compatibility percentage index. 43 easy-to-check features such as: does it support highlighting of bold text using single asterisks? Each feature can be supported in a basic way (one point) or in an advanced way (two points). One point means it basically doesn't interfere with the tool in any negative way. Two points means that it provides active syntax highlighting, for example, or even tool-supported features like shortcuts to insert elements and such. Summing up those two levels for all those 43 features result in a number that can be compared to the maximum level there is, which results in a given percentage.

[00:07:36.319] By definition, Emacs provides full support of all Orgdown levels, and most tools support at least fifty percent of Orgdown1 as long as Orgdown1 syntax doesn't result in some markup conflict or tooling conflict or whatever. This emphasizes the idea that Orgdown can and should be used for personal notes anywhere and in general domains, just like writing emails, for example. I guess the majority of tools with a certain support for Orgdown1 will be in the area of 80s and 90s, percentwise. If Orgdown1 is not enough, there will be future definitions of Orgdown2, 3, or higher which will take more and more syntax elements from the Org Mode syntax and integrate it into the domain of Orgdown.

[00:08:39.519] So far, Orgdown1 is described on a public GitLab page which has already documentation on how to learn Orgdown, some syntax examples, frequently asked questions, and of course, with their answers, a collection of tools that already do support Orgdown in some way, and a few of them did already get evaluated by me and got their OD1 compatibility percentage in a table.

[00:09:07.279] Some ideas on how people can contribute to this new standard is also part of this new site. And of course, now I need your help in order to make this a success story for Org Mode and of course Orgdown. So please do contribute to the GitLab project pages and add tools and their Orgdown1-compatible percentages. For example, a template file is provided, of course. Please do add more parsers. Please use the term Orgdown1 to label tool properties for your own stuff and so that people do realize that your tools are already supporting this general use case of Org Mode. And there is no need to support all the Org Mode in order to profit from Org Mode syntax with Orgdown. You can spread the idea by promoting Orgdown as a separate term compared to Org Mode and its mixed up definition with the Org Mode Elisp implementation. And in case that Orgdown really resonates with you, you can add a formal specification to the GitLab project of Orgdown. I guess that some of the existing formal definitions of Org Mode already do qualify for Orgdown1 by stripping down to the few things Orgdown1 is concentrating on.

[00:10:41.279] You can create, for example, a language server protocol for Orgdown1 which would multiply the possibilities for adapting Orgdown1 in all kinds of editors by giving syntax highlighting, for example. And you may find the idea intriguing that Orgdown1 is a perfect markup language candidate for the Gemini project, which would be, in short, a linked web of plain Orgdown1 files that form a parallel internet without advertisements, malware-bloated web pages, and so forth. It's concentrating on the essential value of information in form of simple text files and links to other simple text files. I would love to see this. happen someday In the meantime, let's kick-start Orgdown with Orgdown1 as the first level. Visit the GitLab page, hand in improvements for the linked tool sections, and spread the brilliant markup design of Org Mode, using Orgdown as a well-defined new standard. Thank you.

Back to the schedule
Previous: Org as an executable format
Next: Using Org-mode to teach programming