: Simple pre-formatted text such as for source code.
: This also respects the line breaks. *bold* is not bold here.
The trouble with that is you cannot easily copy/paste code to/from it, because you'll need to manually add/subtract the : prefix. Delineating the section with:
```
Simple pre-formatted text such as for source code.
This also respects the line breaks. *bold* is not bold here.
```
They’re not mentioned in the article, but org-mode does have syntax for source blocks (a little uglier than Commonmark/Github-flavor markdown’s blocks in my opinion, but it does the same thing and works well).
#+BEGIN_SRC lisp
(format t "Hello world!~&")
#+END_SRC
but it has two things going for it.
One, it's consistent with other blocks, like BEGIN_QUOTE, BEGIN_EXAMPLE, BEGIN_VERSE, etc. (n.b. all four have a default shorthand that gets tab-expanded; <s. <q, <e and <v, respectively) , and with arbitrary user-defined blocks like BEGIN_whatever.
Two, while #+BEGIN_SRC may seem only an unnecessarily verbose way of writing ```, things change when the block starts to look like this:
AKA. a named source block (so I can reference it elsewhere) of Lisp executing in selected Lisp package, with org mode variables injected into it, using noweb syntax (literate programming) for injecting other code blocks[0], which when exporting the document to a different format (say, PDF) will export both code and results of its evaluation, but will not automatically evaluate the code.
This feature makes Org Mode essentially a kind of better Jupyter, with automatic support for any and all possible language that you can plug into Emacs, simultaneously.
--
[0] -- here, it'll paste the literal contents of #+BEGIN_SRC block with #+NAME: preamble at the beginning, and then paste the results of executing a block with #+NAME: some-other-block, with value 3.14 for its :var param, at the end
This deserves a little expansion - Org Mode makes the reasonable-in-context assumption that the user is familiar with Emacs.
At that point, adding or removing a ':' is not a repetitive task. Then the ':' notation gains an advantage because selected lines can be copied and automatically keep their formatted status.
Except one is not always able to use an editor, and assuming people are always able to do something is a great downfall of many products or standards made by people with specific uses cases in mind who think their experiences are universally applicable.
I thought the writeup was about emacs org-mode. Who is planning to use that in a context where the text editor can’t handle basic features from 40+ years ago?
That also works in org-mode, and then you get syntax highlighting for the language etc. It can even open that block to edit in a separate buffer with the right major mode loaded for that language.
The command is org-edit-special bound to C-c ' (by default I think). I use this to dump example blocks which I often use to catch terminal output as well as source code editing. Having structured outputs from test/investigation/exploring that you can rearrange and export to use as documentation for the next time/training costs so little time that I get upset when I can't do it.
I came cross PlantUML recently, it's so much more than a classic diagram tool. I was particularly intrigued by their wireframe system: http://plantuml.com/salt
Org mode is simply awesome and the only reason I open emacs these days. I still haven't managed to find a software, free or paid, which has the same amount of flexibility.
Last I checked, and admittedly it's been a while, parsing full org-mode syntax outside Emacs itself is a nightmare. It's essentially cloning whatever version of org-mode you have in mind.
Not that org-mode's any less for it. I'm no longer a daily user, but I was, for quite some time, to organization a particularly chaotic episode of my work life.
Last I looked into it (mainly with interest for vim), few if any parsers/tooling exist for it outside of emacs; as I recall, people claimed that it apparently has sufficient (undocumented/poorly specified) quirks in the emacs implementation that 100% reproduction is difficult; similar to implementing vim-mode for editor plugins
In which case, its only as standardized as the one implementation; which is exactly how standardized markdown started with (the perl implementation)
Came here just to say that. I had a static blog written in org-mode and converted it over to markdown a couple of weeks ago because there's no good way of converting org-mode to html except by running emacs. So for each article, getting a html representation requires firing up emacs. That's insane.
If there were good (and fast!) js, c, python, etc libraries to fully support parsing org-mode to AST and HTML, only then would it be a viable solution for markup.
If you put the results of org-babel into the buffer, then pandoc handles everything OK.
The one problem I have with pandoc is that when using word export, it loses the table and figure numbers. Mind you, at least I only have to put those in outside emacs :)
> Pandoc only handles a subset of org-mode markup.
To me that's got the same drawbacks as "not standardized". If not all of the existing tools support the standard then there are several de facto standards.
I was just about to say. The GP sounds like they're saying
> there's no good way of converting <markup language> to html except by running <preferred converter>. So for each article, getting a html representation requires firing up <preferred converter>. That's insane.
And how do I use that when I want to interactively convert org-mode to html in javascript? Like countless pure-javascript markdown libraries allow me to do?
not to mention the security hazards of running emacs with any user input from a website.
That you don't – much like you don't get Pandoc Markdown in JavaScript, because Pandoc is not written in JS.
But if you are content with a less featured variation of the markup language (but still more featureful than Markdown), you can get that for JavaScript too: https://xiaoxinghu.github.io/orgajs/syntax
And how do I use that when I want to interactively convert org-mode to html in javascript? Like countless pure-javascript markdown libraries allow me to do?
not to mention the security hazards of running emacs with any user input from a website.
That's a fair point. My own blog runs a two-step process: I export org-mode posts to HTML with Emacs/Org-Mode exporter, and then rewrite the result in my static generator.
Nah, the generator is so full of garbage code that I keep it as a private repo. The generator handles both new posts (org-exported to HTML) and old posts (Wordpress exports I dumped to org mode).
A partial snippet of the code that handles new posts:
What's happening is that I take the HTML generated by Emacs Org Mode exporter, deserialize it to DOM, select a block corresponding to contents (to cut out superfluous stuff I don't need), and then run a bunch of tree-walkers that massages the DOM until it becomes something I can wrap with my site's scaffolding and dump into a file. It's really ugly, but gets the job done.
Yeah. I use markdown hosted file and do the markdown -> html conversion entirely clientside via http://dynalon.github.io/mdwiki/#!index.md. I don't think it's possible to do that at all with orgmode?
To be specific, the canonical format for Pandoc is Pandoc Markdown, which is still my favorite flavor of Markdown (I guess Github-falvored is my second favorite). But Org Mode is even nicer than Pandoc Markdown, so I used Pandoc to convert all my files to Org Mode.
I use Pelican for my static blog, and it takes both markdown and rst. I've automated the process: I convert org to rst using pandoc, and let Pelican take it from there. I literally made a Pelican plugin to do it - so my content directory now just has org files.
First, pandoc does a pretty decent job of converting Org Mode to HTML or several other formats.
Second, "firing" up Emacs sounds odd to Org Mode's target audience. :) We already have Emacs open! (I typed this comment in Emacs).
I don't know how hard it is to make a nice looking website in Org Mode, but to make bland websites for academics (like this schmuck's page: https://www.matem.unam.mx/~omar/), I think Org Mode and org-publish are great. And probably it's not harder to make a nice website with org-publish than with anything else: the trick is being willing to learn CSS. :)
Kulfon [1] is a static site generator that compiles Org Mode to HTML without using Emacs. You can just drop `.org` files in a directory and run a one-command tool to make this work. I use it for my website, mostly to write blog posts. It is also possible to mix Markdown and Org Mode files in a single project/directory.
Kulfon is my own project, so take it with a grain of salt. I've decided to focus on Org Mode as I also believe this format doesn't get the recognition it deserves. It doesn't mean Markdown is bad, au contraire, it is almost perfect. In Org Mode, for instance, I still cannot get used to the source code blocks. It is, however, good to have a choice.
The Org Mode support in Kulfon is not perfect yet, but good enough for most situations. It is based on a JavaScript plugin by Xiaoxing Hu called orgajs [2]. You can use it directly in your project.
One of the motivations for building a SSG with Org Mode was Org Brain [3]. I have a plenty of interconnected notes that I would like to publish on my website « as-is ». This would be rather difficult to do using Markdown format.
I've used org-mode both as an organiser and as a simple markup language. It is fantastic for both and far superior to any other that I've used. I will actually write using org-mode and export to formats for others, often using pandoc (which I invoke using the keyboard from emacs, of course).
One weird thing about markdown and other formats is they don't have a title. So people use heading 1 as their title which is strange and wrong.
I simply love being able to type up a document in an environment I'm comfortable in and then exporting it to whatever format is required at the end: html (document or slideshow), pdf, or even MS Turd. I have stylesheets set up for each that actually make my documents look more professional and consistent than people who use those things directly.
The day org-mode will reach the masses is when the tutorials about it do not even mention the word emacs. Until then, it will inevitably be seen as a thing useful only for emacs users.
Given the options, I think that a decent argument can be made that emacs is the best editor, and that it's unreasonable to use anything that the best — so yeah, one might argue that emacs is the only reasonable editor.
I don't know if I'd go quite that far, but I wouldn't instinctively disagree.
My take is Emacs is the best integrated text processing environment available. But I am not sure it would beat VI/VIM as an text editor.
I don't think most Emacs users could match a good VIM user in text editing speed, but then Emacs can do many other tasks that are hard to replicate in VIM, while being a more than good enough editor.
It is not so much which editor is better, rather what are the user's expectations.
To me this is obvious and has been probably been said a 1000 times before, but sometimes when reading threads about text editors, you would not think so.
I have been working on a Python way to import/export Orgmode files to/from an SQLite database that you can view and query in a native GUI (using Toga[0]). I was writing an Org-mode importing package for Python (to gain access to my Orgzly files and learn Python) until I found Orgnode[1]. I have the GUI table working, but I need to connect Orgnode to it and build an exporting system. You can follow this project at [2].
There is indeed, and it's making me very hopeful for the future of org-mode. Beyond Filestash (great work!) there's the somewhat similar org-web [0], Beorg for iOS [1] and Orgzly for Android [2], all of which them leveraging the power of org-mode without requiring anyone hitting M-x or C-c even once.
What Markdown has going for it is a much wider acceptance as a simple, straightforward way to work with text. Especially on modern devices, users with little or no coding background are successfully being lured into (superior!) plaintext workflows by apps with a great UI, and appear to take to it. iA Writer [A] and Bear [B] are two prominent examples of such apps, and I can't see why they would be any worse (or less popular) apps had they instead opted for org-mode behind the scenes.
This is what org-mode needs to gain widespread adoption, and I'm hoping we're on our way there.
The day jazz will reach the masses is when the reviews about it do not even mention the word "black".
It's created by emacs users, for emacs users, it should absolutely mention that word everywhere and stress its origins, it's already widely adopted and who really cares if somebody who is so superficial that he rejects a superior solution because it originated in a text editor he doesn't like doesn't use it?
> The day jazz will reach the masses is when the reviews about it do not even mention the word "black".
Indeed, and most of them don't nowadays!
> It's created by emacs users, for emacs users, it should absolutely mention that word everywhere and stress its origins
Of course, when you are explaining the history of org-mode you can mention it. Or when you are explaining how to org-mode with emacs. But to promote org-mode as a generic markup language (which I think is a very good idea), any mention of emacs, even indirect, should be best omitted.
> who really cares if somebody who is so superficial that he rejects a superior solution because it originated in a text editor he doesn't like doesn't use it?
I love emacs and I like to use it, no idea who are you taking about. Or was it sarcasm?
After considering two or three dozens of different "lightweight" markup languages (i.e. not flavors) and designing a few (plus at least three failed attempts to improve Markdown), I'm now almost convinced that Scribble [1] or Perl POD [2] have one of the best possible designs. Not that they are optimal, but they are definitely heading at the correct direction.
They are extremely generic: every Scribble syntax is prefixed `@`, every POD construct is either `letter<...>` or `=word`. And yet they are surprisingly unobstructive and readable enough. Compare with BBCode, which is also pretty generic but too annoying.
They are readily extensible and need no special one-off syntaxes for most things. Yes, using asterisks or underscores for emphasis is handy, but how about strike-throughs? Underlines? Non-emphasis italics (e.g. species name)? Language tags? Abbreviations? Do they nest? Do they work in any context? Why not adding some harmless options to the existing constructs? Syntax extensibility should be one of the foremost concerns of markup language design and they got it right.
Edit: I should stress that these concerns are only valid for writings. For casual comments, less is better (ideally no-follow links and verbatim texts should suffice).
I'm a big fan of Perl myself, but when writing POD, I occasionally stumble about the C<...> for inline code.
The problem is that you have to take care that there is no > in the inline code, and if there is, you have to switch to C<< ... >>. With Markdown's `...`, this happened far less often to me.
You are right that it is suboptimal. (I do think that Scribble's choice of braces is not too bad in this regard.) On the other hand, I can't readily type backquotes in my mobile phone or recent macOS [1] so there is a trade-off :-)
[1] Annoyingly enough, macOS Sierra and later maps a backquote to a Won sign in Korean keyboard layouts.
Never read scribble before but I kinda like it. It reminds me of the good parts of latex. As in @action vs \action. Though I don’t like the table syntax as much from a WYSIWYG level (E.g. it doesn’t look table-ly) but for complex tables it don’t matter much. Can you readily extend scribble with Racket and how’s the install/usage story?
I think it is in the default Racket install. And yes, that's a problem; it is actually a Racket code behind the scene so it is fundamentally tied to Racket (that can be good or bad depending on your use case, and some strength points can be attributed to that).
I know we're talking about docs right now, which is where Scribble really shines. And when it comes to blogging/prose, I'd recommend Pollen[1], which is a writing system based on scribble. It is fairly lightweight and extensible with Racket (which is by the way actually a pretty awesome language).
I'm writing my college notes in it and couldn't be happier. The dev is very responsive on mailing lists and would gladly help you out if you have some trouble initially. There is a pretty thorough getting started guide on the linked page. There's a few blogs written in Pollen and even a few books (Ever heard about Flatland? Or Practical Typography?).
Reading the comments here, it feels like people miss the whole point of markdown.
Markdown's raison d'être is, "if you follow these conventions when doing ASCII art formatting, the my program can transform this to HTML or whatever other format".
The conventions being mostly the ones used in the pre-HTML email era, like underlining headings with a bunch of ======.
Orgmode is completely different to that. Orgmode is an "outliner/GTD" at heart, but this aspect has been buried under a ton of features.
Then if you want "prawfishunal qvalitat" advanced formatting, typesetting and layout control what you really want is something like Latex. Yet another whole different thing.
But Markdown was advertised as "a text-to-HTML conversion tool for web writers" [1]. The raison d'être as you stated is not an end goal but a possible benefit. Gruber may have thought that the extensibility of Markdown is done by raw HTML; now we know that's not enough.
The thing about org mode is that it has everything you need to do the full fancy latex typesetting without loosing the ability to export to other formats the way you do if you write raw latex. Of course there are times when you have no choice but to duplicate a block if you are doing something really fancy, but that is a fairly rare occurrence.
Of course Org Mode is completely different, because it can do tons of other stuff. But among it's many features, it also has lightweight markup syntax about which you could claim "if you follow these conventions when doing ASCII art formatting, the my program can transform this to HTML or whatever other format". And the conventions in Org Mode are also email-like in the sense that they don't look out of place in something meant to be plain text. (Maybe finding some large email corpus could answer which syntax is more email-like between Org Mode and Markdown, and maybe Markdown wins on that front, but my point is both syntaxes are lightweight for the most commonly needed markup.)
Org has just much larger scope than Md. The whole feature set of Markdown covers a tiny fraction of Org features.
NOTE: my use case is writing high-quality, good looking technical and user manual-like documentation.
Org-the-format is very close semantically to ReST - most of Org constructs have a direct equivalent in ReST, and vice versa - rather than to Markdown. And Org-the-system is very similar to Sphinx (the documentation/article/paper creation tool in Python) or Scribble. They are functionally equivalent - headless Emacs in Docker with Org/Babel and Sphinx - and it's unfortunately very hard to justify choosing the former over the latter. I know - I just tried this past half a year and failed, even though I could count on a lot of goodwill from my co-workers :(
(I'm ignoring the agenda, timelog, notes, spreadsheet, and all the kitchen sinks which also come with Org because they tend to be of private use, and I'm focusing on professional context)
The situation changes drastically, of course, if you do use Emacs. The Emacs' UI for Org, which is yet another thing from Org-the-format and Org-the-(headless)-executable-exporting-to-html/pdf, is incredibly powerful. Examples of features: storing, pasting and inserting and following links, footnotes, images. Structural modification of the document without hassle (no more missing text after reordering a list!). Ability to edit all code and examples in their corresponding modes (with syntax highlighting, autocomplete, etc.) Ability to run a single chosen code block with a key-press, inserting or updating (or not) the results into document. Support for editing tables - rearranging columns and rows. Latex, PlantUML, and dozens of other languages and tools integration... These are all very nice, very powerful features - and that's on top on whatever conveniences you have already configured in your Emacs, too.
Unfortunately, without the UI, Org is no more useful than Sphinx. On the other hand, no one's going to switch to another editor just to edit the docs, nor should they be forced to.
I like Org. I store my notes and some todo lists in it, I enjoy Babel (support for IPython/Jupyter notebook style development but polyglot), I maintain some parts of my blog in Org (long and unwieldy otherwise lists nested to a few levels). I cannot, however, see any reason to introduce Org as a tool for my team at work, unless they all see the light and come over to Emacs side :)
PS. a bit off-topic but I need to vent a bit: the API of Org is just awful! Functions for traversing the structure of the document are both in outline and org modes, and it's hard to know which is where and why. There are myriads of ways to get the current element, none of which is simple. A lot of the processing is still based on text search and substitution, instead of AST. It's not trivial to go from source to AST, either. I found at least 2 bugs in macro expansion code. I wanted to syntax-highlight the results of a code block (JSON was returned) and I had to hack around in header/keyword parsing for this. To be honest - some of my enthusiasm vanished after the experience :(
I do not have anything online at the moment to show, but a small document processor i wrote some time ago used a @-based syntax which was essentially a tree of named nodes with attributes - essentially the same thing as XML, but with a simpler syntax that was something like:
@Foo; is a standalone empty node named Foo
@Foo[aa] has a "aa" attribute without a value
@Foo[bb=cc] has a "bb" attribute with "cc" value
@Foo[dd="hello, world",ee] has "dd" attribute with "hello, world" value and "ee" attribute without value
@Foo{blah} has a "blah" text child
@Foo{blah @Bar;} has "blah" and Bar children
@Foo Bar shortcut for @Foo{Bar}
@Foo{!{...}!} has ... as unprocessed content
So you can type something like @P{This is a @I nice @Link[target=foo]{example} of @TT{code} @Smile;.} which would be sort of equivalent to XML <P>This is a <I>nice</I> <Link target="foo">example</Link> of <TT>code</TT> <Smile/></P> (but with less repetition, especially for longer documents).
In my processor the tree is passed to a script that does the actual handling by going through the nodes, children, etc and creating the output text (HTML or whatever) - the processor itself has no knowledge of specific node names, any meaning lies in the scripts.
My biggest issue with the above though is that i do not like editing markup by hand, so at some point i want to replace all the above with a GUI tool that does the same job but in a more graphical way without the need for (visible to the user) markup syntax (so the above example would be edited as just text but with the "nice", "example" and "code" bits having representational styling).
having to close paragraphs is useless. It moves to the user of the markup a concern that is only of interest to the implementor. That should we exactly the other way round.
I prefer html5, where you can leave tags open as if there's no tomorrow.
This is just the way i have the scripts setup since it makes more sense for me for paragraphs to be full nodes that contain their children content, but it is trivial to make empty P nodes act as paragraph separators.
It is not a trivial matter when you are writing the markup manually. If you require to open and close paragraphs it becomes very cumbersome for no real gain (just a tiny amount of convenience for the programmer of the parser).
The ideal case is TeX, where paragraphs are separated by a blank line.
With trivial i meant that it is trivial to have a script that makes @P; a separator (or start marker) if you prefer to work that way. I made the system script-driven with a generic syntax exactly because i didn't want to hardcode any specific way of working with the nodes.
As for TeX, i personally dislike markup languages where whitespace is treated in a special way since this is source code, which often needs some style of its own and sometimes that depends on context.
To me seeing where a paragraph - or any other "long" element - begins and ends can be helpful and if anything, i consider the lack of syntax for this in my markup as a negative (but i couldn't come up with a clean and unambiguous syntax for adding an optional "closing" bit). I compensate for that using comments (which look like @# Blah until the end of line), but it is a workaround.
And also FWIW i prefer to have the markup map to the underlying tree of nodes clearly than introduce "magic" that in some cases can make things harder even for writers.
Keep in mind though that this is for long(ish) documents, like a large tutorial, guide, manual, etc not short comments like this one here. For anything that is around the size of a common blog post or shorter, something more adhoc like Markdown is probably better.
Perhaps i used a wrong description, but i meant having special cases/multiple uses and specifically about text markup languages. If every other element of the document tree, like sections, links, emphasis, references, images, figures, etc is marked using explicit syntax then using whitespace for paragraphs is inconsistent and can often be misleading since this will also need to be context sensitive as you do not want paragraphs to be inserted in every node that can have children.
But this is obviously a stylistic preference as to me that sounds too much trouble for no gain at all - which is basically your response above :-P.
But as i wrote in my original message, i'm not a big fan of these plaintext formats and i'd rather work using a "WYSIWYM" editor that uses these nodes behind the scenes instead of having the user write the markup by hand. But that is obviously much harder to implement (and if the tool handles the nodes for you the syntax doesn't matter at all anyway). Still, to me that is the ideal:-).
Yes, it was mainly inspired by Lout (although i think there is a much older system that used a similar syntax - and GNU TexInfo also uses something similar, but i didn't knew about that at the time), however IIRC Lout doesn't use a generic syntax.
In a case of great minds think alike (you, Eli Barzilay, and Matthew Flatt), this (especially the square brackets and curly braces purposes) is remarkably similar to what Racket ended up using, for the @-reader syntax that's used by Scribble document processing: https://docs.racket-lang.org/scribble/reader.html#%28part._....
Those are not lightweight markup languages at all?
The main point of markdown is that it is supposed to look like a normal & readable text document in its own right. The transformation to html isn't absolutely necessary for readability.
I'm leaning towards agreement with you, especially for embedded API docs in code.
I've been using Scribble for embedded API docs for years,[1] and the formatted result looks great, and is very powerful and extensible (Scribble is actually a better LaTeX), but it's not nearly as readable in code as it could be.
I think I actually preferred my earlier three-comment-character-Texinfo format I had before, and I even wrote a converter to Scribble for it (so that it would look idiomatic), except Texinfo format just couldn't handle Racket types.
Now that I've put Racket on hold while I Rust a bit, in the interests of job-hunting, I'm happy to see Rust is using Markdown (coincidentally, also with the three-comment-character prefix).
[1] Here's one formatted example, everything coming from the code files and package metadata, no separate documentation files: https://www.neilvandyke.org/racket/roomba/
As a huge fan of Perl and very comfortable writing POD, I despise POD. I would much prefer Markdown for documentation. It's easier to write and easier to read. Just try creating lists in each.
I haven't tried dozens but I really really wanted to like asciidoc and rst. But they both require me to type n number of '=' for title string of length n. I confess I fail to see the utility in this kind of design.
I'm still looking (Scribble seems anything but lightweight!). Perlpod probably looks perfect but I have to see more.
I feel the same way about RST; really wanted to like it, fought with it, gave up because Sphinx consistently seems to make simple things hard.
Regarding section titles, I think the theory is it makes it easier to stick new header levels into a document.
(For those who aren't familiar with RST: If it sees underlines like ====, ----, ^^^^ or ~~~~~, it decides what the header levels are based on the order in which it sees them.)
In practice, it means a typo makes it completely ignore your header, you have to learn a set of acceptable characters for headers, and there's no way to start a document with anything less than shouty H1.
Reasonable for text...for most text that's skeuomorphic with regards to the printed word (in most senses). But... what is there for that which is beyond? A response to the linked comment mentions TEI (Text Encoding Initiative). Anything else? Is it too vast a problem in that we should make due with solutions that cover 90% of use-cases? Ah, but does that limit potential future development as people mold themselves to the constraints placed on them by the tools and what those tools allow?
I like Wikitext[1] which is Mediawiki's markup. Mediawiki is the software that runs Wikipedia. I have a personal Mediawiki that I use for taking notes and it works a lot better than org-mode in that it is easy to make tables, nicely formatted outlines , hypertext, etc. Chrome has a plugin that lets you edit textboxes in emacs too so you can use a real text editor instead of just chrome textboxes.
Maybe I'm just old but I miss the old MoinMoin syntax. A lot of markups are so complicated (mediawiki) I'd rather just write HTML.
For my personal notes I now just use vim and a custom syntax file to give color to special names and headings. I've used markdown before but it seemed like different tools treated the language slightly different.
I do the same for my personal notes. Something like (the actual contents differ because I take notes in my native tongue):
if exists("b:current_syntax")
finish
endif
syn match diaryHashtag "\w\@<!#[A-Za-z]\+"
syn match diaryInlineCode "`[^`]\+`"
syn match diaryLineMarker "^[ \t]*\%([0-9]\+\.\|[*-]\)\S\@!"
syn match diaryInlineMarker "=>\|\S\@<!(\?\%(i\{1,3}\|iv\|vi\{0,3}\|ix\|x\))\S\@!"
syn match diaryInlineDate "\<\%(today\|yesterday\|tomorrow\|\%(\%(next\|last\)\s\)\=\%(mon\|tue\|wed\|thu\|fri\|sat\|sun\)\|20\d\d-\d\d\%(-\d\d\)\=\)"
syn match diaryInlineTime "\<\%(\d\d\=:\d\d\|morning\|afternoon\|night\)"
hi default link diaryHashtag String
hi default link diaryInlineCode Delimiter
hi default link diaryLineMarker Statement
hi default link diaryInlineMarker Statement
hi default link diaryInlineDate Comment
hi default link diaryInlineTime Comment
let b:current_syntax = 'diary'
But this system is entirely unusable for longer and potentially public writings.
I used something similar, along with a few additions to add timestamp as a column on the left etc.
I've since switched over to org-mode though, I find that the agenda integration and a couple of org-journal plugins make for easy task management. I'd really like an alternative that lets me handle this on mobile, so far I've tried termux and the github edit file interface, and neither are as satisfactory.
While reading the thing I could not help but feel like what I'd call "sensible markdown" is both very close and bijective to org syntax. The trouble comes when I need to define what is "sensible markdown" which is a thing I never attempted to do, but pragmatically works very well. It seems like it's CommonMark + GFM (for tables, checklists, and syntax-aware fenced code blocks mostly) + MarkdownLint[0], the latter enforcing stringent rules that makes Markdown very consistent and portable as well as prune the nonsensical stuff (like double space before newline or underline headings). It's fantastic to use with VScode[1] or vim-ale.
Some pet peeves:
I really don't ever get the argument about Markdown URLS. Being able to do both [](url) vs [][ref] is awesome (the latter I liberally use when writing long form docs). If one finds it so annoying one would make the mistake like three times and then it'd be burned into one's brain due to selective pressure. Or just use [][ref] style (which is more readable anyway since you don't have the URL right in the middle of a sentence).
Also, very personal thing but my brain seems to hate /italics/ as it branch predicts into parsing that as a regex.
What drives me nuts though is all the variants and ad hoc syntaxes like JIRA's or this very board's, which sit right in the uncanny valley of nonsense.
Gak, yeah, I empathize. JIRA was a pain point for me too.
I take comprehensive notes using org-mode (including all of my false turns, dead ends and "explore this later"s) and when I need to paste something into a ticket I export via ox-jira.el and copy/paste what I need. It works much better than the author's modest README might lead you to believe, and of course it's hackable.
To date, I haven't seen a flavor of Markdown that has a comment feature. I use it extensively to hide all my notes that don't have a place in the final exported document people will read.
What we need is more time machines so we can go back in the past and make even more future choices. Because just splitting amongst the choices we have is so .. limiting.
I do kind of wish we only had one markdown flavour. Maybe why we only have one org mode is because of its lack of ubiquitousness? If it had an electron windows version would it be the same?
The commensurate note is, everything here (Bar one) says it's a stalking horse for Emacs
I refuse to use a plain text editor for my personal notes. Bold, italic, underline, text highlighting... these are all things that help me organize text and draw my attention to certain areas. Asterisks simply don't do the same job, visually.
Luckily for you Emacs lets you set the faces (emacs's name for syntax highlighting) however you want it. You get the best of both worlds: convenient keyboard interface and marked up text in the editor.
The authors argument that Markdown should be discarded because there are several competing implementations isn't valid.
For many years (even now), we have several competing implementations of HTML, yet the HTML document is the dominant presentational document format (and UI layout language). It hasn't done anything to hurt adoption.
The fact that Markdown does have a common subset of features, and that Markdown is widely interoperable with a vast amount of products is why it wins. As far as I can tell Org-Mode markup is used within Emacs and really nowhere else.
This looks really nice, do you have plans to implement text search of note contents?
No matter how methodical I get with tags and hierarchies, nothing beats search for recall.
It's arguable that the fact that there are multiple implementations is itself a sign of success. If Org-Mode was to become widely adopted, it's pretty much inevitable it would get multiple implementations too.
indeed it is. When something is used by a lot of people, they will find use cases not covered sufficiently and will try to extend. Some of these will survive and be absorbed back, some will not. Normal evolutionary pressure at work.
The argument isn't that Markdown is bad because there are competing implementations. The argument is that Markdown is bad because there is no standard for those implementations to adhere to, so they end up being wildly incompatible. With HTML, there will be browser differences, but there's a pretty well-defined standard which browsers try to adhere to; there will be bugs, but at least you can know you're writing standards-compliant HTML, and then work around particular browser engines as necessary.
You say Markdown has a common set of features, but what is that common set? There's no standard, and I find myself surprisingly frequently struggle with figuring out what's the correct way in a particular markdown engine to do what I need to do.
An example is that in Reddit's markdown; this text:
```
if (true) {
console.log("hi");
}
```
will all end up as inline code, with all the newlines and extra whitespace stripped out. The correct way to do it in Reddit's markdown is to hit the space bar (n+1)*4 times before each line, where n is the indentation level. Some (but presumably not all) other markdown engines would render it as a code block.
Markdown engines are also wildly inconsistent about when they treat something as a link, and whether they require a blank line between a paragraph and code blocks or lists.
They seem to mostly agree about how explicit links and bold and emphasis and headings work though, so if that's your consistent common set of features, I suppose you're right.
> You say Markdown has a common set of features, but what is that common set? There's no standard, and I find myself surprisingly frequently struggle with figuring out what's the correct way in a particular markdown engine to do what I need to do.
Yeah, CommonMark is awesome, and if the argument was about CommonMark and not Markdown in general, I'd be on the other side of the argument. However, most Markdown renderers don't implement CommonMark.
I did some investigation into this recently. My hope is to make at least new reddit support it this year. Can't promise anything about old.reddit.com though
> The argument is that Markdown is bad because there is no standard for those implementations to adhere to, so they end up being wildly incompatible.
This argument is valid, but…
> An example is that in Reddit's markdown; this text: [snipped] will all end up as inline code, with all the newlines and extra whitespace stripped out.
This does not validate the argument. Implementations defer to John Gruber’s Markdown Syntax Documentation.[1] It is insufficient to be used as a standard (hence your argument being valid), but does (in some cases) provide a common subset of features compatible everywhere. The “fenced” code block is not included in Gruber’s original Markdown, but became so popular due to GitHub that people come to expect it. It is still not part of “Standard Markdown” though.
there are lots of other issues. AFAICT HTML is allowed inline in markdown but the flowing inline HTML is interpretted differently depending on implementation
some markdown text
<div>
some
**inline**
text
</div>
some more markdown text
some will take that as one block. some will process each line separately. some will convert the asterisks
...
HTML inlined into markdown is easily my least favourite feature of markdown. In my opinion it breaks the very point of of MD (namely that it's formatting makes as much sense in a graphical render as it does in a plain text editor).
Has anyone found a good GFM to HTML converter that does not call out to a SaaS service (often GitHub)? I keep ending up in use cases where I need to do this conversion or do a live preview without having the data leave the box. When I was looking around previously I found out that under the hood they were using the GitHub API to actually do the preview.
Commonmark (https://commonmark.org) exists, has a fairly well defined standard, and the reference implementations are not hard to reason about. They are part of several thousands of larger codebases right now, too.
Org-mode on the other hand is basically an emacs thing that has never been seen in the wild outside maybe as a pandoc input? Which is coincidentally another tool I almost never actually use by itself. And I have literally no idea how ota reference implementation works or on which languages could I embed it and how.
I'm pretty sure my experience isn't that rare too.
Commonmark didn't really accomplish much in terms of standardization. The problem is that they didn't take seriously comments that they didn't support everything they needed to support in order for it to be a standard. The most prominent example is support for math, which is extremely common. That wouldn't be so bad if there were support to escape processing, but they weren't willing to support that either.
The response is to tell anyone that they need to look for an implementation with the proper extensions for equations or whatever you might need that's not currently supported. There's not much to be gained from having a standard if it doesn't ensure document compatibility among competing implementations. Commonmark is nothing but yet another version of markdown.
It doesn't help that there's no unambiguous CFG for Markdown. Any new implementation is more or less on their own with many using odd tricks to get around the inherent ambiguity.
HTML has a lock-in because it's supported by web browsers directly, exactly like JS. I have a profound dislike for anything SGML-related but what can I do? Display my website as a PDF? At best I can transpile an other format into HTML.
HTML and JS have succeeded in spite of their clunkiness, not because of it.
Markdown on the other hand has no such lock-in, mainly because it usually gets transpiled into HTML or other formats. Replacing it is a lot easier and can be done incrementally without client support.
The several competing implementations of HTML are not a feature, they are a complication we have to deal with. This has not hurt adoption because of the nature of the marketplace.
The 'number of implementations' issue with org-mode is that there are almost no implementations outside of Emacs. Standardization by obscurity is not a very compelling virtue, and the opportunity for widespread adoption has passed.
AsciiDoc! As nice as org-mode syntax, but with "=" instead of "*". Also, has code blocks so copy&paste is nicer. Also, has one giant document explaining everything.
I agree. My experience with asciidoc is that it's much more comprehensive and straightforward than trying to manage all the competing markdown implementations while still maintaining legible syntax and a full feature set
My first love was AsciiDoc and it still is. I never got into markdown as much as AsciiDoc because it did what I wanted which was to generate documentation for software. However, when keeping track of stuff I am working on, snippets of possible code and completion status, etc. then Org-Mode has my attention. I have tried doing the same in markdown but most themes don't handle TODO as gracefully as ones targeting org-mode.
Org mode is great, at work I use it since half a year to keep myself organized. For instance when I'm debugging something, I can keep notes and clues or the sometimes not avoidable request that just won't fit into the issue tracker.
I recently came to the same conclusion as the article but was dismayed by the performance of the popular Vim plugin (and wasn't ready to switch to emacs), so I wrote a very, very minimal implementation which is enough to get me headings, folding, tables (including formula solving, the syntax for which is currently left as an exercise for the reader), unordered lists, dates, and various other things.
It's very much a work in progress (in particular, the syntax files expect a graphical Vim) but it's definitely improved my note-taking. Requires Python 3 support.
It does look nice, and I'd be more than happy to put some effort and use Org-Mode, instead of Markdown, if only
- There was a standardized release outside emacs which would consistently provide the same results.
- There was an easy way to render documents (like the Perl script markdown has)
- There was serious support for plugins for my editor for easy rendering to pdf/html/whatever.
Once I played with tables in org-mode, I never turned back to markdown. I am not sure if there is another markup tool which looks at tables as good org-mode does.
Unconvincing. Markdown surely has way better tool support.
The lack of standardisation is probably the best argument, but I suspect that is mostly not a problem for Org mode simply because barely anyone uses it. If it were as popular as Markdown you'd find plenty of non-standard extensions and slightly different implementations.
... goes on to name one tool (pandoc) that parses Org-Mode (and also parses Markdown. I would in fact guess pandoc is used much more often for the latter than the former).
> Org-Mode Has Excellent Tool Support
> this is not an article about Emacs
... goes on to describe the "tool support" in Emacs. Sorry, but the paragraph title here really implies we're going to be talking about a range of tools, not just Emacs.
And then to conclude:
> With this blog article I wanted to point out the usefulness of Org-mode even when you are not using Emacs as an writing tool.
Can anyone point me to where exactly in the article the author has done this?
Org-Mode is great if you use Emacs. Try installing the Org-Mode addon in your non-Emacs IDE of choice, and you'll hit the same "partially implemented/not-yet-supported/etc." issues you would using an obscure markdown parser. In this regard, Markdown is much more "standardised" than Org-Mode—a standard exists for both, but the level of adherance to that standard in terms of the total number of parsers out there is undoubtedly higher for Markdown.
I don't really like opinions such as yours, because you're nitpicky.
This article actually doesn't give it justice, because Org-Mode is more than an alternative to Markdown because it specifies formatting for time-based tasks, so you can specify deadlines and you can also track the time you work on those tasks. You can use Org-Mode for task management in a way that other formats are not suitable.
Examples of tooling:
1. GitHub can render Org-Mode files (in gists, etc)
2. you can find task management tools for iPhone / Android that can work with Org-Mode, one example being: https://beorgapp.com/
Tooling is definitely at least part of why I don't use org, and I use emacs as my primary editor. I love the concept of org, but getting it synced and using it on mobile were not trivial, and features that I'd expect from any similar solution were all painfully manual. I wanted to love org, but I just haven't found a way to make it work for me, and tooling is certainly part of the problem.
Org-mode looks very similar to markdown. Almost so that I would call it pointlessly different.
The word standardization gets abused a lot in our industry. Usually it implies something that 1) has a non ambiguous specification, 2) is widely used. 3) is endorsed by some standards body or cross industry organization or simply so widely used that it effectively is a standard 4) has multiple independent implementations (tools, parsers, websiters, etc.)
Org-mode has a specification (https://orgmode.org/); is at this point in time not widely used; has not been endorsed or proposed to a standards body like e.g. w3c, ietf, etc.; has a very limited amount of implementations. Declaring it a standard is meaningless until that is fixed.
The Github flavor of markdown has a decent specification (https://github.github.com/gfm/), many implementations of e.g. parsers for different languages, many websites/tools/etc. using it. It's not at this point a formal standard but the previous makes it more or less a de-facto industry standard that is widely used, with a reference OSS implementation and many other parsers aiming to be compatible.
If you are implementing markdown support, you could do worse than pick this flavor. Several other flavors are equally well specified, have similarly good tool support and industry endorsement, and might very well be considered standards in their own right.
Of course, like with Json, there's a long tail of not so great parsers that have implementation specific bugs/quirks/omissions/features, etc.
> Org-mode looks very similar to markdown. Almost so that I would call it pointlessly different.
Just a minor note on this: Org-mode was created in 2003 (the syntax a bit earlier) and Markdown in 2004, so I think this was a case of parallel evolution, each unaware of the other, not intentional deviation.
Edit: And the use cases were different. Org was designed as a syntax for an outliner, and Markdown was designed as a syntax for prose. Both are plain text and optimized for readability in their pre-processed form, but maybe it's the fact that they are so similar that's remarkable.
The point is that as soon as one project looked like it was gaining critical mass, the other project should have conceded defeat and adopted the winning format. Because as we all know, the major problem with open source is there can be more than one of something.
you are implying that there is a standardized markdown flavor. pretty much every parser forks the "standard". even though markdown-ish is more common than org-mode, i don't think there is a clear winner here. common standards do emerge from open source, but we have to let the competition play out until the end. and tbfh, you aren't playing the game correctly if you just give up and die without overwhelming proof that your project in irrelevant.
That is a ridiculous notion. People like myself escaped to free software in order to avoid the imposition of a vision by a single corporate entity, like you have with MS/Apple.
People are not uniform, they don't all like the same music, books etc. so why should this not be true for tools?
In his original documentation for Markdown, Gruber acknowledges an number of influences. Mostly common plaintext email conventions of the time, but also Setext, reStructuredText, and more by name.
He did not include reference to org-mode, so he probably did not know of it at the time. (Although maybe Aaron Swartz was familiar with org-mode, and provided cross-pollination?)
Most likely as you mentioned, md and org both evolved independently from similar ancestors
Org-mode does fill the primary use-case for Markdown that I’ve seen, since GitHub will render it just like they do Markdown.
The small slice of Org-mode demonstrated in this article might look like just a Markdown clone, but within Emacs you can do things like a Jupypter notebook with Org-Babel, which GitHub renders statically. Granted, it’s possible to do these things without Emacs (or a watered down plugin for another editor).
Superficially org looks similar to markdown, but the kinds of manipulations you can do with TODO lists, calendars, tables within emacs is like magic. It's nothing like markdown when you use it this way.
I agree that Org-mode and Markdown are pointlessly different! The latter has no excuse for existing, given that the former both long predates it in time and vastly exceeds it in power.
> given that the former both long predates it in time
Org-mode's initial release was in 2003 (I can't find a specific month); Markdown's was in March 2004. So Org-mode predates Markdown by about a year. Personally, as someone who is not an Emacs user, I heard of Markdown years before I ever heard of Org-mode.
I think you have made several incorrect statements.
I love Markdown, but Org does a lot more, because:
* It supports a variety of timestamps, which is critical for implementing task management workflows. In fact, I think Org has more users for it's time management features than for anything else.
* It supports tables with spreadsheet-like formulas. So you can include data in your documents and perform computations. This opens the door to accounting, billing and part lists when doing project management, etc.
* It extends Emacs outline-mode, so it has a really consistent hierarchical structure, properties, tags and whatnot. Very important in a number of use cases.
* It supports literate programming, which I don't use, but can reasonably replace Jupyter-like notebooks.
* It defines a number of link types, which can be extended. Out of the box, it does support DOI for example. Which is important for many people doing reference management.
I mainly intended to say I think Org is much more standardized than Markdown because there is at least a unique reference implementation and a unique reference document describing the format. Whereas for Markdown, you do have many slightly different implementations and attempts at standardization, despite Markdown being an order of magnitude simpler.
In places like GitLab, people are taking advantage of this by running Emacs in batch mode inside a container to effectively use the reference implementation for export-to-other-formats purposes.
It's not an ideal situation, though. And I hope someone creates a truly independent library. There is a Ruby parser employed by GitHub and GitLab which covers a decent subset of Org. Furthermore, Orgzly and vim-orgmode are pretty much closer to implementing a much bigger subset of Org.
I think the solution is not just an implementation, but rather a language description independent of an implementation. A reference description would allow org mode format to be usable in perpetuity.
As a side-note: As a regular emacs and org-mode user, not a fan of the date format and lack of flexibility in picking repeating schedules.
> not a fan of the date format and lack of flexibility in picking repeating schedules.
I haven't used repeaters that much, but I was under the impression that they were very, very flexible. At least much more flexible than a typical todo app. What don't you like about them?
For reference, here's some documentation about them:
I am quite familiar with the available options for repeated entries. But Something as usual as 2nd Thursday of every month requires me to write a diary-float sexp, which is not intuitive to edit. If it is difficult to use for a programmer like me, I can only imagine how complicated it is for other people. Moreover, diary-float sexp expressions are most definitely not helping the argument of usability outside emacs.
> But Something as usual as 2nd Thursday of every month requires me to write a diary-float sexp, which is not intuitive to edit.
I agree that it could be better, but I'd be surprised if it was something that was typically expressible in other programs. So the fact that it's doable at all seems great, and does indicate that it's flexible.
Since you said it lacked flexibility, I was wondering if you had an example of something that was not expressible in Emacs org-mode but that was expressible elsewhere.
> Moreover, diary-float sexp expressions are most definitely not helping the argument of usability outside emacs.
Well, it's not elisp, is it? It's just sexps. It may as well be JSON, but more concise.
Actually, Google Calendar does provide the choice of repeating every 2nd Thursday of every month. But it has its own limitation. For example, Google calendar does not let me do every 2nd and 4th Thursday of the month.
Just to clarify, I am not criticizing org-mode for not implementing in comparison to others. The lack of flexibility I suggest is the date format itself, which does not even allow specifying 2nd Thursday of the month for example. diary-float allows it, but is not intuitive.
I intend to write an interactive scheduling tool for org-mode when I can spare the time. Like regex-builder, but for dates.
I don't know if this is doable from org-mode but it seems to me like this could be a viable, more readable alternative to diary-float.
For your example of 2nd Thursday from every month, instead of:
%%(dairy-float t 4 2)
you could have:
&%%(let ((day-of-week (calendar-day-name date))
(day (cadr date)))
(and (= day-of-week "Thursday")
(> day 7)
(<= day 14)))
That's seems more readable to someone that hasn't read what the parameters of dairy-float mean. For your second example of every 2nd and 4th Thursday:
&%%(let ((day-of-week (calendar-day-name date))
(day (cadr date)))
(and (= day-of-week "Thursday")
(or (and (> day 7) (<= day 14))
(and (> day 21) (<= day 28)))))
It being a programming language might make it unintuitive to use by a non-programmer, but I don't think you can get anymore flexible than this. Also, org-mode's attractiveness being that everything is in plain text, I'm not sure there is a syntax that would be more readable than properly written code.
I'm not a super big fan of Org timestamps for dates, either. Flexibility is OK.
But I wish we had something like Remind [1] where you can define events based on e.g. Easter dates, skip recurring events if they fall into a holiday or move them according to a rule.
In particular, I hate I have to change all bank holidays every year. Remind got this right. There's some added complexity, though.
A nice thing about Org is the pragmatic way it deals with recurring events. You clone them and adjust at will, manually. So you can deal with really odd ways of re-scheduling meetings.
Oh, that's an interesting point. Actually, for Easter [0], you could technically write a piece of code to figure out when Easter is. But on a more practical note, maybe Org-mode should have event based entries, which in my opinion also speaks to a lack of flexibility. It should be possible to anchor dates on other events, so you can have one annual calendar file to replace at once, which may be automatically generated. Like wanting to plan something a week before Easter?
There was a unique reference implementation for Markdown, too. It was ignored and extended by various popular services. If anybody fully implemented Org-mode outside of Emacs, it would likely have run into the same issue.
A reference implementation isn't standardization. Markdown had a reference implementation and yet subsequent implementations still diverged. The reference implementation also had bugs, which were fixed over time, thus changing the de-facto standard.
At this point, Markdown does have a real standard, CommonMark. GitHub-Flavored Markdown was modified to become an extension to CommonMark (it's literally just a few extra features on top of CommonMark at this point). There are of course non-CommonMark-based implementations still (such as MultiMarkdown) but at this point anyone adding Markdown support to a project should be using CommonMark or GFM.
I actually started using orgmode completely outside of Emacs.
The beginning workflow was VS Code, and I certainly appreciate your note about the partially implemented featureset of most orgmode non-Emacs clients.
I then discovered Orgzly (http://www.orgzly.com/) which I hooked up to VS Code using Drop Box free. Orgzly is fantastic and supports a lot more of orgmode than most clients. (edited to add: orgzly is an android app)
Now, however, I've dropped VS Code in favour of Emacs running on either Windows 10 or OS X terminals. There's a decent cheat sheet (https://orgmode.org/orgcard.pdf) that I refer to a lot.
So my advice would be to give orgmode a try using Orgzly at first, then get a simple instance of Emacs going and use the cheat sheet to make things easier to learn and dip into. I think the push to try to do things outside of Emacs is throwing away the orgmode original codebase baby with the Emacs bathwater. I know Emacs is considered scarier even than vim, but for my simple use case it works well. It was even fairly easy to get the org-jira plugin working to pull my Jira tickets into TODO items.
> Now, however, I've dropped VS Code in favour of Emacs
I've tried on VS Code and also given up (on Org, not on vscode, which was far more central to my workflow than Org was).
I'd tried SyncOrg on Android, but had not heard of Orgzly. I see from your link it's on FDroid—just retried doing a search on FDroid for 'org-mode' to see what else is out there that I missed, and nothing comes up (neither SyncOrg not Orgzly). FDroid really need to fix their search, and/or makes of those clients really need to fix their metadata; not sure which.
I may give Orgzly a go, but tbh without decent desktop client (short of switching to Emacs, which I shan't be doing), I'm not sure how worthwhile it will be. I may try some pandoc automation...
Does Orgzly work with Syncthing out of the box now? Last time I tried Orgzly it only used Dropbox for sync, which is what made me drop it at that time.
As far as I know, Orgzly still only works with Dropbox, which is a shame. I wish I had the programming skill to add that support, since Orgzly is open source.
However, Orgzly can sync with local directories on your Android device, so could Syncthing work via that route?
Not sure what you mean by 'out of the box', but orgzly supports local directory syncing which can indeed be used in conjunction. Source: this is my setup.
> Org-Mode Makes Sense Outside of Emacs
> Org-Mode Has Excellent Tool Support
> this is not an article about Emacs
I honestly believe that org-mode alone is reason enough to keep emacs installed on your system. It's full-featured enough that you could ignore everything else Emacs does and still find it a very powerful application.
> the level of adherance to that standard in terms of the total number of parsers out there is undoubtedly higher for Markdown.
Sure, there is less tooling because it is used less, but that's not an argument against embracing it. The more people who use it, the more parsers will get written for it.
250 comments
[ 2.4 ms ] story [ 251 ms ] threadOne, it's consistent with other blocks, like BEGIN_QUOTE, BEGIN_EXAMPLE, BEGIN_VERSE, etc. (n.b. all four have a default shorthand that gets tab-expanded; <s. <q, <e and <v, respectively) , and with arbitrary user-defined blocks like BEGIN_whatever.
Two, while #+BEGIN_SRC may seem only an unnecessarily verbose way of writing ```, things change when the block starts to look like this:
AKA. a named source block (so I can reference it elsewhere) of Lisp executing in selected Lisp package, with org mode variables injected into it, using noweb syntax (literate programming) for injecting other code blocks[0], which when exporting the document to a different format (say, PDF) will export both code and results of its evaluation, but will not automatically evaluate the code.This feature makes Org Mode essentially a kind of better Jupyter, with automatic support for any and all possible language that you can plug into Emacs, simultaneously.
--
[0] -- here, it'll paste the literal contents of #+BEGIN_SRC block with #+NAME: preamble at the beginning, and then paste the results of executing a block with #+NAME: some-other-block, with value 3.14 for its :var param, at the end
At that point, adding or removing a ':' is not a repetitive task. Then the ':' notation gains an advantage because selected lines can be copied and automatically keep their formatted status.
The very first line after the disclaimer even reads "Please do note that this is not about Emacs".
Write in any text editor, and a tiny JS boilerplate turns it into nicely-rendered HTML.
People complain a bit too much about productivity and context switching.
Not that org-mode's any less for it. I'm no longer a daily user, but I was, for quite some time, to organization a particularly chaotic episode of my work life.
Last I looked into it (mainly with interest for vim), few if any parsers/tooling exist for it outside of emacs; as I recall, people claimed that it apparently has sufficient (undocumented/poorly specified) quirks in the emacs implementation that 100% reproduction is difficult; similar to implementing vim-mode for editor plugins
In which case, its only as standardized as the one implementation; which is exactly how standardized markdown started with (the perl implementation)
If there were good (and fast!) js, c, python, etc libraries to fully support parsing org-mode to AST and HTML, only then would it be a viable solution for markup.
IIRC last time I tried this (long ago) there were a number of gaps in things like org-mode tables.
At the limiting case, the (common or uncommon) elisp extensions (e.g. org-babel) will likely never be processed by third-party tools.
The one problem I have with pandoc is that when using word export, it loses the table and figure numbers. Mind you, at least I only have to put those in outside emacs :)
To me that's got the same drawbacks as "not standardized". If not all of the existing tools support the standard then there are several de facto standards.
> there's no good way of converting <markup language> to html except by running <preferred converter>. So for each article, getting a html representation requires firing up <preferred converter>. That's insane.
But if you are content with a less featured variation of the markup language (but still more featureful than Markdown), you can get that for JavaScript too: https://xiaoxinghu.github.io/orgajs/syntax
not to mention the security hazards of running emacs with any user input from a website.
A partial snippet of the code that handles new posts:
https://gist.github.com/TeMPOraL/c401f12d50d4e1d4f94492e3d0f...
What's happening is that I take the HTML generated by Emacs Org Mode exporter, deserialize it to DOM, select a block corresponding to contents (to cut out superfluous stuff I don't need), and then run a bunch of tree-walkers that massages the DOM until it becomes something I can wrap with my site's scaffolding and dump into a file. It's really ugly, but gets the job done.
Of course the canonical format for pandoc is markdown.
So far, I've not seen any major issues.
Second, "firing" up Emacs sounds odd to Org Mode's target audience. :) We already have Emacs open! (I typed this comment in Emacs).
I don't know how hard it is to make a nice looking website in Org Mode, but to make bland websites for academics (like this schmuck's page: https://www.matem.unam.mx/~omar/), I think Org Mode and org-publish are great. And probably it's not harder to make a nice website with org-publish than with anything else: the trick is being willing to learn CSS. :)
Kulfon is my own project, so take it with a grain of salt. I've decided to focus on Org Mode as I also believe this format doesn't get the recognition it deserves. It doesn't mean Markdown is bad, au contraire, it is almost perfect. In Org Mode, for instance, I still cannot get used to the source code blocks. It is, however, good to have a choice.
The Org Mode support in Kulfon is not perfect yet, but good enough for most situations. It is based on a JavaScript plugin by Xiaoxing Hu called orgajs [2]. You can use it directly in your project.
One of the motivations for building a SSG with Org Mode was Org Brain [3]. I have a plenty of interconnected notes that I would like to publish on my website « as-is ». This would be rather difficult to do using Markdown format.
[1]: https://kulfon.org/ [2]: https://github.com/xiaoxinghu/orgajs [3]: https://github.com/Kungsgeten/org-brain
Maybe Ruby's implementation is best for now since github is using it.
One weird thing about markdown and other formats is they don't have a title. So people use heading 1 as their title which is strange and wrong.
I simply love being able to type up a document in an environment I'm comfortable in and then exporting it to whatever format is required at the end: html (document or slideshow), pdf, or even MS Turd. I have stylesheets set up for each that actually make my documents look more professional and consistent than people who use those things directly.
Without Emacs, org-mode is just weird markdown.
The way it can quickly link between different types of unrelated content just doesn't make sense outside Emacs.
That is the entire point. If I can only use it inside emacs then I will only use it inside emacs.
So, are you saying that the title of the article is bogus? Or that emacs is the only reasonable editor?
Given the options, I think that a decent argument can be made that emacs is the best editor, and that it's unreasonable to use anything that the best — so yeah, one might argue that emacs is the only reasonable editor.
I don't know if I'd go quite that far, but I wouldn't instinctively disagree.
I don't think most Emacs users could match a good VIM user in text editing speed, but then Emacs can do many other tasks that are hard to replicate in VIM, while being a more than good enough editor.
It is not so much which editor is better, rather what are the user's expectations.
To me this is obvious and has been probably been said a 1000 times before, but sometimes when reading threads about text editors, you would not think so.
Emacs takes an everything and the kitchen sink approach and org-mode embraces that.
I have been working on a Python way to import/export Orgmode files to/from an SQLite database that you can view and query in a native GUI (using Toga[0]). I was writing an Org-mode importing package for Python (to gain access to my Orgzly files and learn Python) until I found Orgnode[1]. I have the GUI table working, but I need to connect Orgnode to it and build an exporting system. You can follow this project at [2].
[0]: https://toga.readthedocs.io/en/latest/ [1]: http://members.optusnet.com.au/~charles57/GTD/orgnode.html [2]: https://gitlab.com/bthall/orcbench
What Markdown has going for it is a much wider acceptance as a simple, straightforward way to work with text. Especially on modern devices, users with little or no coding background are successfully being lured into (superior!) plaintext workflows by apps with a great UI, and appear to take to it. iA Writer [A] and Bear [B] are two prominent examples of such apps, and I can't see why they would be any worse (or less popular) apps had they instead opted for org-mode behind the scenes.
This is what org-mode needs to gain widespread adoption, and I'm hoping we're on our way there.
[0] https://github.com/DanielDe/org-web [1] https://beorgapp.com/ [2] http://www.orgzly.com/ [A] https://ia.net/writer [B] https://bear.app/
It's created by emacs users, for emacs users, it should absolutely mention that word everywhere and stress its origins, it's already widely adopted and who really cares if somebody who is so superficial that he rejects a superior solution because it originated in a text editor he doesn't like doesn't use it?
Indeed, and most of them don't nowadays!
> It's created by emacs users, for emacs users, it should absolutely mention that word everywhere and stress its origins
Of course, when you are explaining the history of org-mode you can mention it. Or when you are explaining how to org-mode with emacs. But to promote org-mode as a generic markup language (which I think is a very good idea), any mention of emacs, even indirect, should be best omitted.
> who really cares if somebody who is so superficial that he rejects a superior solution because it originated in a text editor he doesn't like doesn't use it?
I love emacs and I like to use it, no idea who are you taking about. Or was it sarcasm?
"Only if you use EMacs, as Org-Mode is impossible to implement outside of EMacs".
Source: tried once as someone who never used org-mode or emacs. Did not go well.
They are extremely generic: every Scribble syntax is prefixed `@`, every POD construct is either `letter<...>` or `=word`. And yet they are surprisingly unobstructive and readable enough. Compare with BBCode, which is also pretty generic but too annoying.
They are readily extensible and need no special one-off syntaxes for most things. Yes, using asterisks or underscores for emphasis is handy, but how about strike-throughs? Underlines? Non-emphasis italics (e.g. species name)? Language tags? Abbreviations? Do they nest? Do they work in any context? Why not adding some harmless options to the existing constructs? Syntax extensibility should be one of the foremost concerns of markup language design and they got it right.
Edit: I should stress that these concerns are only valid for writings. For casual comments, less is better (ideally no-follow links and verbatim texts should suffice).
[1] https://docs.racket-lang.org/scribble/
[2] https://perldoc.perl.org/perlpod.html
The problem is that you have to take care that there is no > in the inline code, and if there is, you have to switch to C<< ... >>. With Markdown's `...`, this happened far less often to me.
[1] Annoyingly enough, macOS Sierra and later maps a backquote to a Won sign in Korean keyboard layouts.
I'm writing my college notes in it and couldn't be happier. The dev is very responsive on mailing lists and would gladly help you out if you have some trouble initially. There is a pretty thorough getting started guide on the linked page. There's a few blogs written in Pollen and even a few books (Ever heard about Flatland? Or Practical Typography?).
[1] http://pollenpub.com
Markdown's raison d'être is, "if you follow these conventions when doing ASCII art formatting, the my program can transform this to HTML or whatever other format".
The conventions being mostly the ones used in the pre-HTML email era, like underlining headings with a bunch of ======.
Orgmode is completely different to that. Orgmode is an "outliner/GTD" at heart, but this aspect has been buried under a ton of features.
Then if you want "prawfishunal qvalitat" advanced formatting, typesetting and layout control what you really want is something like Latex. Yet another whole different thing.
[1] https://daringfireball.net/projects/markdown/
Org has just much larger scope than Md. The whole feature set of Markdown covers a tiny fraction of Org features.
NOTE: my use case is writing high-quality, good looking technical and user manual-like documentation.
Org-the-format is very close semantically to ReST - most of Org constructs have a direct equivalent in ReST, and vice versa - rather than to Markdown. And Org-the-system is very similar to Sphinx (the documentation/article/paper creation tool in Python) or Scribble. They are functionally equivalent - headless Emacs in Docker with Org/Babel and Sphinx - and it's unfortunately very hard to justify choosing the former over the latter. I know - I just tried this past half a year and failed, even though I could count on a lot of goodwill from my co-workers :(
(I'm ignoring the agenda, timelog, notes, spreadsheet, and all the kitchen sinks which also come with Org because they tend to be of private use, and I'm focusing on professional context)
The situation changes drastically, of course, if you do use Emacs. The Emacs' UI for Org, which is yet another thing from Org-the-format and Org-the-(headless)-executable-exporting-to-html/pdf, is incredibly powerful. Examples of features: storing, pasting and inserting and following links, footnotes, images. Structural modification of the document without hassle (no more missing text after reordering a list!). Ability to edit all code and examples in their corresponding modes (with syntax highlighting, autocomplete, etc.) Ability to run a single chosen code block with a key-press, inserting or updating (or not) the results into document. Support for editing tables - rearranging columns and rows. Latex, PlantUML, and dozens of other languages and tools integration... These are all very nice, very powerful features - and that's on top on whatever conveniences you have already configured in your Emacs, too.
Unfortunately, without the UI, Org is no more useful than Sphinx. On the other hand, no one's going to switch to another editor just to edit the docs, nor should they be forced to.
I like Org. I store my notes and some todo lists in it, I enjoy Babel (support for IPython/Jupyter notebook style development but polyglot), I maintain some parts of my blog in Org (long and unwieldy otherwise lists nested to a few levels). I cannot, however, see any reason to introduce Org as a tool for my team at work, unless they all see the light and come over to Emacs side :)
PS. a bit off-topic but I need to vent a bit: the API of Org is just awful! Functions for traversing the structure of the document are both in outline and org modes, and it's hard to know which is where and why. There are myriads of ways to get the current element, none of which is simple. A lot of the processing is still based on text search and substitution, instead of AST. It's not trivial to go from source to AST, either. I found at least 2 bugs in macro expansion code. I wanted to syntax-highlight the results of a code block (JSON was returned) and I had to hack around in header/keyword parsing for this. To be honest - some of my enthusiasm vanished after the experience :(
In my processor the tree is passed to a script that does the actual handling by going through the nodes, children, etc and creating the output text (HTML or whatever) - the processor itself has no knowledge of specific node names, any meaning lies in the scripts.
My biggest issue with the above though is that i do not like editing markup by hand, so at some point i want to replace all the above with a GUI tool that does the same job but in a more graphical way without the need for (visible to the user) markup syntax (so the above example would be edited as just text but with the "nice", "example" and "code" bits having representational styling).
I prefer html5, where you can leave tags open as if there's no tomorrow.
The ideal case is TeX, where paragraphs are separated by a blank line.
As for TeX, i personally dislike markup languages where whitespace is treated in a special way since this is source code, which often needs some style of its own and sometimes that depends on context.
To me seeing where a paragraph - or any other "long" element - begins and ends can be helpful and if anything, i consider the lack of syntax for this in my markup as a negative (but i couldn't come up with a clean and unambiguous syntax for adding an optional "closing" bit). I compensate for that using comments (which look like @# Blah until the end of line), but it is a workaround.
And also FWIW i prefer to have the markup map to the underlying tree of nodes clearly than introduce "magic" that in some cases can make things harder even for writers.
Keep in mind though that this is for long(ish) documents, like a large tutorial, guide, manual, etc not short comments like this one here. For anything that is around the size of a common blog post or shorter, something more adhoc like Markdown is probably better.
just to nitpick: except for APL, white space is treated in a special way in all programming languages to separate tokens :)
Using it to separate text (words and paragraphs) makes perfect sense in this context.
But this is obviously a stylistic preference as to me that sounds too much trouble for no gain at all - which is basically your response above :-P.
But as i wrote in my original message, i'm not a big fan of these plaintext formats and i'd rather work using a "WYSIWYM" editor that uses these nodes behind the scenes instead of having the user write the markup by hand. But that is obviously much harder to implement (and if the tool handles the nodes for you the syntax doesn't matter at all anyway). Still, to me that is the ideal:-).
you will pry plain text editors from my cold, dead hands!
https://en.wikipedia.org/wiki/Lout_(software)
I made an Emacs mode for it: https://www.neilvandyke.org/scribble-emacs/
The main point of markdown is that it is supposed to look like a normal & readable text document in its own right. The transformation to html isn't absolutely necessary for readability.
I've been using Scribble for embedded API docs for years,[1] and the formatted result looks great, and is very powerful and extensible (Scribble is actually a better LaTeX), but it's not nearly as readable in code as it could be.
I think I actually preferred my earlier three-comment-character-Texinfo format I had before, and I even wrote a converter to Scribble for it (so that it would look idiomatic), except Texinfo format just couldn't handle Racket types.
Now that I've put Racket on hold while I Rust a bit, in the interests of job-hunting, I'm happy to see Rust is using Markdown (coincidentally, also with the three-comment-character prefix).
[1] Here's one formatted example, everything coming from the code files and package metadata, no separate documentation files: https://www.neilvandyke.org/racket/roomba/
I'm still looking (Scribble seems anything but lightweight!). Perlpod probably looks perfect but I have to see more.
Is there a markup that can do numbered lists?
1. first item
2. second
3. and so on
Markdown does parse that, but it seems superfluous to me tbh.
Regarding section titles, I think the theory is it makes it easier to stick new header levels into a document.
(For those who aren't familiar with RST: If it sees underlines like ====, ----, ^^^^ or ~~~~~, it decides what the header levels are based on the order in which it sees them.)
In practice, it means a typo makes it completely ignore your header, you have to learn a set of acceptable characters for headers, and there's no way to start a document with anything less than shouty H1.
Nice idea, though.
> Is there a markup that can do numbered lists?
Correctly and usably? NOPE.
Reasonable for text...for most text that's skeuomorphic with regards to the printed word (in most senses). But... what is there for that which is beyond? A response to the linked comment mentions TEI (Text Encoding Initiative). Anything else? Is it too vast a problem in that we should make due with solutions that cover 90% of use-cases? Ah, but does that limit potential future development as people mold themselves to the constraints placed on them by the tools and what those tools allow?
Just thinking out loud, per usual.
[1] https://meta.wikimedia.org/wiki/Help:Wikitext_examples
But adopting trumps perfection, hence, GFM is probably the most reasonable choice for new applications today.
For my personal notes I now just use vim and a custom syntax file to give color to special names and headings. I've used markdown before but it seemed like different tools treated the language slightly different.
I've since switched over to org-mode though, I find that the agenda integration and a couple of org-journal plugins make for easy task management. I'd really like an alternative that lets me handle this on mobile, so far I've tried termux and the github edit file interface, and neither are as satisfactory.
Some pet peeves:
I really don't ever get the argument about Markdown URLS. Being able to do both [](url) vs [][ref] is awesome (the latter I liberally use when writing long form docs). If one finds it so annoying one would make the mistake like three times and then it'd be burned into one's brain due to selective pressure. Or just use [][ref] style (which is more readable anyway since you don't have the URL right in the middle of a sentence).
Also, very personal thing but my brain seems to hate /italics/ as it branch predicts into parsing that as a regex.
What drives me nuts though is all the variants and ad hoc syntaxes like JIRA's or this very board's, which sit right in the uncanny valley of nonsense.
[0]: https://github.com/DavidAnson/markdownlint
[1]: https://github.com/DavidAnson/vscode-markdownlint
Gak, yeah, I empathize. JIRA was a pain point for me too.
I take comprehensive notes using org-mode (including all of my false turns, dead ends and "explore this later"s) and when I need to paste something into a ticket I export via ox-jira.el and copy/paste what I need. It works much better than the author's modest README might lead you to believe, and of course it's hackable.
https://github.com/stig/ox-jira.el
To date, I haven't seen a flavor of Markdown that has a comment feature. I use it extensively to hide all my notes that don't have a place in the final exported document people will read.
I do kind of wish we only had one markdown flavour. Maybe why we only have one org mode is because of its lack of ubiquitousness? If it had an electron windows version would it be the same?
The commensurate note is, everything here (Bar one) says it's a stalking horse for Emacs
- Show styling sigils and keep text plain;
- Show styling sigils AND style the text;
- Hide styling sigils and style the text.
In my experience, the middle option really hits the sweet spot.
For many years (even now), we have several competing implementations of HTML, yet the HTML document is the dominant presentational document format (and UI layout language). It hasn't done anything to hurt adoption.
The fact that Markdown does have a common subset of features, and that Markdown is widely interoperable with a vast amount of products is why it wins. As far as I can tell Org-Mode markup is used within Emacs and really nowhere else.
- original org: https://demo.filestash.app/api/export/hnorg/text/org/emacs.o...
- markdown: https://demo.filestash.app/api/export/hnorg/text/markdown/em...
- html: https://demo.filestash.app/api/export/hnorg/text/html/emacs....
- pdf: https://demo.filestash.app/api/export/hnorg/application/pdf/...
- more fancy plain text: https://demo.filestash.app/api/export/hnorg/text/plain/emacs...
there's more builtin and with plugin you can say extend the github markdown to cope with jekyll, hugo, ...etc
You say Markdown has a common set of features, but what is that common set? There's no standard, and I find myself surprisingly frequently struggle with figuring out what's the correct way in a particular markdown engine to do what I need to do.
An example is that in Reddit's markdown; this text:
will all end up as inline code, with all the newlines and extra whitespace stripped out. The correct way to do it in Reddit's markdown is to hit the space bar (n+1)*4 times before each line, where n is the indentation level. Some (but presumably not all) other markdown engines would render it as a code block.Markdown engines are also wildly inconsistent about when they treat something as a link, and whether they require a blank line between a paragraph and code blocks or lists.
They seem to mostly agree about how explicit links and bold and emphasis and headings work though, so if that's your consistent common set of features, I suppose you're right.
There is CommonMark specification: https://commonmark.org.
> On redesign, a slightly-edited version of CommonMark. On old reddit, it's still snudown.
(and mobile apps have their own markdown)
> New Reddit note: Indented code blocks are the only form of code block that works on Old Reddit. Use them for compatibility
https://www.reddit.com/wiki/markdown#wiki_code_blocks_and_in...
maybe in a few years there is going to be syntax highlighting, one can hope :) (slack doesn't have it either, but even discord has it...)
This argument is valid, but…
> An example is that in Reddit's markdown; this text: [snipped] will all end up as inline code, with all the newlines and extra whitespace stripped out.
This does not validate the argument. Implementations defer to John Gruber’s Markdown Syntax Documentation.[1] It is insufficient to be used as a standard (hence your argument being valid), but does (in some cases) provide a common subset of features compatible everywhere. The “fenced” code block is not included in Gruber’s original Markdown, but became so popular due to GitHub that people come to expect it. It is still not part of “Standard Markdown” though.
[1]: https://daringfireball.net/projects/markdown/syntax
* GFM = Github Flavoured Markdown, even if Gitlab have very cheekily taken on the same initialism for their (in fairness, highly compatible) flavour.
https://github.com/markedjs/marked
Org-mode on the other hand is basically an emacs thing that has never been seen in the wild outside maybe as a pandoc input? Which is coincidentally another tool I almost never actually use by itself. And I have literally no idea how ota reference implementation works or on which languages could I embed it and how.
I'm pretty sure my experience isn't that rare too.
There are a couple of vim plugins. I don't know whether they're any good.
https://www.reddit.com/r/vim/comments/4ms4z0/org_mode_which_...
Commonmark didn't really accomplish much in terms of standardization. The problem is that they didn't take seriously comments that they didn't support everything they needed to support in order for it to be a standard. The most prominent example is support for math, which is extremely common. That wouldn't be so bad if there were support to escape processing, but they weren't willing to support that either.
The response is to tell anyone that they need to look for an implementation with the proper extensions for equations or whatever you might need that's not currently supported. There's not much to be gained from having a standard if it doesn't ensure document compatibility among competing implementations. Commonmark is nothing but yet another version of markdown.
HTML and JS have succeeded in spite of their clunkiness, not because of it.
Markdown on the other hand has no such lock-in, mainly because it usually gets transpiled into HTML or other formats. Replacing it is a lot easier and can be done incrementally without client support.
The 'number of implementations' issue with org-mode is that there are almost no implementations outside of Emacs. Standardization by obscurity is not a very compelling virtue, and the opportunity for widespread adoption has passed.
bunch of bindings - https://github.com/asciidoc , etc.
Also Oreilly publishing officially supports Asciidoc for Atlas publishing - http://docs.atlas.oreilly.com/writing_in_asciidoc.html
I recently came to the same conclusion as the article but was dismayed by the performance of the popular Vim plugin (and wasn't ready to switch to emacs), so I wrote a very, very minimal implementation which is enough to get me headings, folding, tables (including formula solving, the syntax for which is currently left as an exercise for the reader), unordered lists, dates, and various other things.
It's very much a work in progress (in particular, the syntax files expect a graphical Vim) but it's definitely improved my note-taking. Requires Python 3 support.
The lack of standardisation is probably the best argument, but I suspect that is mostly not a problem for Org mode simply because barely anyone uses it. If it were as popular as Markdown you'd find plenty of non-standard extensions and slightly different implementations.
... goes on to name one tool (pandoc) that parses Org-Mode (and also parses Markdown. I would in fact guess pandoc is used much more often for the latter than the former).
> Org-Mode Has Excellent Tool Support
> this is not an article about Emacs
... goes on to describe the "tool support" in Emacs. Sorry, but the paragraph title here really implies we're going to be talking about a range of tools, not just Emacs.
And then to conclude:
> With this blog article I wanted to point out the usefulness of Org-mode even when you are not using Emacs as an writing tool.
Can anyone point me to where exactly in the article the author has done this?
Org-Mode is great if you use Emacs. Try installing the Org-Mode addon in your non-Emacs IDE of choice, and you'll hit the same "partially implemented/not-yet-supported/etc." issues you would using an obscure markdown parser. In this regard, Markdown is much more "standardised" than Org-Mode—a standard exists for both, but the level of adherance to that standard in terms of the total number of parsers out there is undoubtedly higher for Markdown.
This article actually doesn't give it justice, because Org-Mode is more than an alternative to Markdown because it specifies formatting for time-based tasks, so you can specify deadlines and you can also track the time you work on those tasks. You can use Org-Mode for task management in a way that other formats are not suitable.
Examples of tooling:
1. GitHub can render Org-Mode files (in gists, etc)
2. you can find task management tools for iPhone / Android that can work with Org-Mode, one example being: https://beorgapp.com/
3. in a text editor all you really need is syntax highlighting, but yes, you can find plugins for many editors, not as evolved as Emacs's, but acceptable, e.g. https://marketplace.visualstudio.com/itemdetails?itemName=to...
Speaking of apps like no. 2, show me TODO apps that synchronize text files to Dropbox, using your format of choice that's not Org-Mode.
Is tooling really a reason for why you're not using Org-Mode, or is it because you're too conservative to try it?
The word standardization gets abused a lot in our industry. Usually it implies something that 1) has a non ambiguous specification, 2) is widely used. 3) is endorsed by some standards body or cross industry organization or simply so widely used that it effectively is a standard 4) has multiple independent implementations (tools, parsers, websiters, etc.)
Org-mode has a specification (https://orgmode.org/); is at this point in time not widely used; has not been endorsed or proposed to a standards body like e.g. w3c, ietf, etc.; has a very limited amount of implementations. Declaring it a standard is meaningless until that is fixed.
The Github flavor of markdown has a decent specification (https://github.github.com/gfm/), many implementations of e.g. parsers for different languages, many websites/tools/etc. using it. It's not at this point a formal standard but the previous makes it more or less a de-facto industry standard that is widely used, with a reference OSS implementation and many other parsers aiming to be compatible.
If you are implementing markdown support, you could do worse than pick this flavor. Several other flavors are equally well specified, have similarly good tool support and industry endorsement, and might very well be considered standards in their own right.
Of course, like with Json, there's a long tail of not so great parsers that have implementation specific bugs/quirks/omissions/features, etc.
Just a minor note on this: Org-mode was created in 2003 (the syntax a bit earlier) and Markdown in 2004, so I think this was a case of parallel evolution, each unaware of the other, not intentional deviation.
Edit: And the use cases were different. Org was designed as a syntax for an outliner, and Markdown was designed as a syntax for prose. Both are plain text and optimized for readability in their pre-processed form, but maybe it's the fact that they are so similar that's remarkable.
People are not uniform, they don't all like the same music, books etc. so why should this not be true for tools?
He did not include reference to org-mode, so he probably did not know of it at the time. (Although maybe Aaron Swartz was familiar with org-mode, and provided cross-pollination?)
Most likely as you mentioned, md and org both evolved independently from similar ancestors
https://daringfireball.net/projects/markdown/syntax
The small slice of Org-mode demonstrated in this article might look like just a Markdown clone, but within Emacs you can do things like a Jupypter notebook with Org-Babel, which GitHub renders statically. Granted, it’s possible to do these things without Emacs (or a watered down plugin for another editor).
Only at the very basic feature set of Org mode. But Org also allows for properties, and tags, and timestamps, and deadlines, etc. etc.
Org-mode's initial release was in 2003 (I can't find a specific month); Markdown's was in March 2004. So Org-mode predates Markdown by about a year. Personally, as someone who is not an Emacs user, I heard of Markdown years before I ever heard of Org-mode.
I love Markdown, but Org does a lot more, because:
* It supports a variety of timestamps, which is critical for implementing task management workflows. In fact, I think Org has more users for it's time management features than for anything else.
* It supports tables with spreadsheet-like formulas. So you can include data in your documents and perform computations. This opens the door to accounting, billing and part lists when doing project management, etc.
* It extends Emacs outline-mode, so it has a really consistent hierarchical structure, properties, tags and whatnot. Very important in a number of use cases.
* It supports literate programming, which I don't use, but can reasonably replace Jupyter-like notebooks.
* It defines a number of link types, which can be extended. Out of the box, it does support DOI for example. Which is important for many people doing reference management.
If you're going to say that, you should list some of them (with corrections).
If I did, I'd be eager to correct them. What were they?
> I love Markdown, but Org does a lot more
I agree. Org is great, as I said above.
I don't think I criticise Org anywhere in my comment, I was purely questioning the points in the article about non-Emacs use.
I mainly intended to say I think Org is much more standardized than Markdown because there is at least a unique reference implementation and a unique reference document describing the format. Whereas for Markdown, you do have many slightly different implementations and attempts at standardization, despite Markdown being an order of magnitude simpler.
In places like GitLab, people are taking advantage of this by running Emacs in batch mode inside a container to effectively use the reference implementation for export-to-other-formats purposes.
It's not an ideal situation, though. And I hope someone creates a truly independent library. There is a Ruby parser employed by GitHub and GitLab which covers a decent subset of Org. Furthermore, Orgzly and vim-orgmode are pretty much closer to implementing a much bigger subset of Org.
As a side-note: As a regular emacs and org-mode user, not a fan of the date format and lack of flexibility in picking repeating schedules.
I haven't used repeaters that much, but I was under the impression that they were very, very flexible. At least much more flexible than a typical todo app. What don't you like about them?
For reference, here's some documentation about them:
https://orgmode.org/manual/Repeated-tasks.html
https://orgmode.org/manual/Timestamps.html#Timestamps
https://www.gnu.org/software/emacs/manual/html_node/org/Time...
https://www.gnu.org/software/emacs/manual/html_node/emacs/Se...
I agree that it could be better, but I'd be surprised if it was something that was typically expressible in other programs. So the fact that it's doable at all seems great, and does indicate that it's flexible.
Since you said it lacked flexibility, I was wondering if you had an example of something that was not expressible in Emacs org-mode but that was expressible elsewhere.
> Moreover, diary-float sexp expressions are most definitely not helping the argument of usability outside emacs.
Well, it's not elisp, is it? It's just sexps. It may as well be JSON, but more concise.
Just to clarify, I am not criticizing org-mode for not implementing in comparison to others. The lack of flexibility I suggest is the date format itself, which does not even allow specifying 2nd Thursday of the month for example. diary-float allows it, but is not intuitive.
I intend to write an interactive scheduling tool for org-mode when I can spare the time. Like regex-builder, but for dates.
For your example of 2nd Thursday from every month, instead of:
you could have: That's seems more readable to someone that hasn't read what the parameters of dairy-float mean. For your second example of every 2nd and 4th Thursday: It being a programming language might make it unintuitive to use by a non-programmer, but I don't think you can get anymore flexible than this. Also, org-mode's attractiveness being that everything is in plain text, I'm not sure there is a syntax that would be more readable than properly written code.[1] https://www.gnu.org/software/emacs/manual/html_node/emacs/Se...
But I wish we had something like Remind [1] where you can define events based on e.g. Easter dates, skip recurring events if they fall into a holiday or move them according to a rule.
In particular, I hate I have to change all bank holidays every year. Remind got this right. There's some added complexity, though.
A nice thing about Org is the pragmatic way it deals with recurring events. You clone them and adjust at will, manually. So you can deal with really odd ways of re-scheduling meetings.
[1] https://www.roaringpenguin.com/wiki/index.php/Remind
[0] https://www.timeanddate.com/calendar/determining-easter-date...
However, I'd prefer if all these things were merged into mainline.
[1] https://orgmode.org/worg/org-faq.html
At this point, Markdown does have a real standard, CommonMark. GitHub-Flavored Markdown was modified to become an extension to CommonMark (it's literally just a few extra features on top of CommonMark at this point). There are of course non-CommonMark-based implementations still (such as MultiMarkdown) but at this point anyone adding Markdown support to a project should be using CommonMark or GFM.
The beginning workflow was VS Code, and I certainly appreciate your note about the partially implemented featureset of most orgmode non-Emacs clients.
I then discovered Orgzly (http://www.orgzly.com/) which I hooked up to VS Code using Drop Box free. Orgzly is fantastic and supports a lot more of orgmode than most clients. (edited to add: orgzly is an android app)
Now, however, I've dropped VS Code in favour of Emacs running on either Windows 10 or OS X terminals. There's a decent cheat sheet (https://orgmode.org/orgcard.pdf) that I refer to a lot.
So my advice would be to give orgmode a try using Orgzly at first, then get a simple instance of Emacs going and use the cheat sheet to make things easier to learn and dip into. I think the push to try to do things outside of Emacs is throwing away the orgmode original codebase baby with the Emacs bathwater. I know Emacs is considered scarier even than vim, but for my simple use case it works well. It was even fairly easy to get the org-jira plugin working to pull my Jira tickets into TODO items.
I've tried on VS Code and also given up (on Org, not on vscode, which was far more central to my workflow than Org was).
I'd tried SyncOrg on Android, but had not heard of Orgzly. I see from your link it's on FDroid—just retried doing a search on FDroid for 'org-mode' to see what else is out there that I missed, and nothing comes up (neither SyncOrg not Orgzly). FDroid really need to fix their search, and/or makes of those clients really need to fix their metadata; not sure which.
I may give Orgzly a go, but tbh without decent desktop client (short of switching to Emacs, which I shan't be doing), I'm not sure how worthwhile it will be. I may try some pandoc automation...
https://search.f-droid.org/?q=orgzly&lang=en
https://search.f-droid.org/?q=org-mode&lang=en
I only use Emacs for org-mode stuff so far. For pretty much anything else I'm using VS Code.
If you're interested, the ~/.emacs file I use is at https://gist.github.com/anthonyclarka2/28543be1a5cbebd0d3d96...
Along with SyncThing and Emacs in laptop, that's my preferred organising system for the last 6 months or so.
However, Orgzly can sync with local directories on your Android device, so could Syncthing work via that route?
I honestly believe that org-mode alone is reason enough to keep emacs installed on your system. It's full-featured enough that you could ignore everything else Emacs does and still find it a very powerful application.
> the level of adherance to that standard in terms of the total number of parsers out there is undoubtedly higher for Markdown.
Sure, there is less tooling because it is used less, but that's not an argument against embracing it. The more people who use it, the more parsers will get written for it.