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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.