3 ms·
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
by fouc 8y ago
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.
- neilv 8y agoI'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/ https://www.neilvandyke.org/racket/roomba/