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.
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 :(
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/
@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).
I made an Emacs mode for it: https://www.neilvandyke.org/scribble-emacs/
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!
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?).
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?
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.
1. first item
2. second
3. and so on
Markdown does parse that, but it seems superfluous to me tbh.
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