search

adamdruppe / arsd

This is a collection of modules that I've released over the years. Most of them stand alone, or have just one or two dependencies in here, so you don't have to download this whole repo.
http://arsd-official.dpldocs.info/arsd.html
530 stars 128 forks source link

Reformat README as markdown #167

Closed spikespaz closed 6 years ago

adamdruppe commented 6 years ago

I hate markdown but I'll allow it for github.

spikespaz commented 6 years ago

@adamdruppe Out of curiosity, why do you hate markdown?

Menelion commented 6 years ago

I thought I am the only person in this world to hate Markdown :).
Two spaces at the end of the line to make a <br> and those f...reaking syntactically meaningful indentations just drive me nuts. And yes, numbered lists! why numbers (especially those awful 1. — next line — 1. — next line — 1.) instead of something nifty, like # on each line? The link syntax is not too appealing, either (aha, brackets first, parentheses next)... To be continued, I guess.

spikespaz commented 6 years ago

@Menelion Well, I love markdown. It's easy to write, fast to parse, and readable in both raw and rendered form. That's not to say it doesn't have its issues. There are some issues with syntax, especially the lists as you said above, but it doesn't really bother me. The reason you don't have # for numbered lists is because it is meant to be readable before rendering. As stated on the original specification.

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

Source

It's not a normal "markup" language. If it was only meant to be read after rendered we would just use HTML or BBCode.

The issues arise when other "extension" standards are imposed over the original specification. Things like CommonMark, GFM, MD2, Markdown Extra, etc. all muddy up the clean and beautiful syntax in the original specification as stated above. But there really isn't any harm done, because you can just chose not to use those features. You aren't required to use it after all. You can just use the simple rich text parts of it like bold, italics, underline, inline code, quote blocks, etc. All of those make sense and are fairly straightforward in my opinion.

Just my three cents.

Edit: Also you don't need two spaces to break the line. Adjacent lines are concatenated into one paragraph element. Just add two line breaks where you want the <br/>.