News for hackers. Stuff that matters.
Re:Org-Mode Is One of the Most Reasonable Markup Languages t... by fouc on Wednesday April 10, 2019 @06:42AM (#19623399)
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.

Re:Org-Mode Is One of the Most Reasonable Markup Languages t... by neilv on Wednesday April 10, 2019 @07:55AM (#19623722)
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/