Live data from Hacker News

Thoughts on Markdown

smashingmagazine.com

31–40 of 167 posts

Re: Thoughts on Markdown

#31

As a developer that really likes to document stuff I don't like markdown. It's limited and as the article states too fragmented. I started using AsciiDoc a while back. It's like markdown but with more advanced options for true documentation stuff like charts, tables (formatted!), diagrams and more.

I share the same opinion. Its limit make it useful only for a very small set of use cases. It's being used a lot for code documentation, but MD is bad fit for documentation. Good documentation requires a lot more formatting and cross-referencing than you'd think. Every language I'm using that has been using MD (for embedded and online docs) added extensions, resulting in more fragmentation. So in general I switch bet…

I agree with both these points. Inter-document references are bad in markdown and wiki style formats. Wikipedia is replete with overlapping and contradictory information that should be pulled from a single source.

Do you have any ideas re link-rot, or underlying assets changing and semantic links becoming invalid? How do you reference a code asset whose name could change, what will not only replace all references in the code but also in the documentation?

Re: Thoughts on Markdown

#32

The discussion reminds me a little of the one around LaTeX in the scientific community. Latex is extremely powerful but reading the raw source of a text is a pain. WISYWIG is just so much more comfortable when writing, but MS Word sucks in its own specific and manifold ways (as does LibreOffice). HTML is still not nice to read, too much boilerplate tags required. Markdown source however is mostly well-readable in a p…

The problem is not writing or reading LaTeX, properly written LaTeX is very readable. It's easy to maintain and understand, and Bibtex for bibliographies works fine once you've gotten used to it. The problems start once you have to convert this to MS Word, which is essentially impossible with any advanced LaTeX document which will invariably contain complex formulas and also include hacks and adjustments in the pream…

You're right: LaTeX is very readable. I've never understood the complaints about the system. What's so hard about writing `\section{Introduction}` or `$R \int_0^1 f dx$`?

After a bit of learning on your first document (perhaps requiring half the time of one of the first of dozens of edits you'll be making, if the document is important), what you get is (a) ease of transition between formats (article in journal becomes chapter in thesis in about 3 minutes work) and (b) beautiful output, not just in mathematics but in support for many language characters, hyphenation hints, etc.

On publishers, I wrote a book for Springer-Nature, and they wanted LaTeX. I wouldn't have published with them, if not.

Re: Thoughts on Markdown

#33
Markdown is merely the lowest common denominator of what is essentially a jungle of weird and wonderful wiki languages. The reason it is so under-specified is that it emerged out of the Ruby community in a time where the whole point of Ruby was that it was a scripting language without a lot of appreciation for things like types or specifications. The first serious attempts to unit test and specify ruby itself actually came out of the JRuby community. Which had an obvious need to cover all the complicated stuff that Ruby did so they could handle all the edge cases in the same way. You see the same with other scripting languages where the obsession with specifying what things like Javascript or Python actually do came later in the life of the languages.

I think the main reason for the popularity of Markdown is that is minimal, forgiving, and uses things that are kind of intuitive for basic formatting. * for bold, - for bullets, etc. Similar compatibility issues between various implementations exist for things like Json, Yaml, HTML, etc. Some of these things even have IETF or W3C specifications nowadays. The specifications usually come after things get popular; rarely before.

Whatever the ruby markdown library did was the specified behavior of Markdown for some time. And then of course it caught on and several alternate implementations emerged for different languages; each with their own features added or interpretations of features. Then Github adopted it, added a few features they needed and then it went mainstream in a big way by virtue of world+dog using Github.

At this point Markdown is collection of features that may or may not work depending on which library and language you use; or even where you use it. The simple stuff works everywhere. But your mileage may vary with some of the more advanced stuff like tables for example. Mostly, the Github dialect seems dominant for the simple reason that that is a popular place to find a lot of markdown content.

The problem with alternatives is that they are comparatively less widely used and therefore a bit more obscure. You need good library support across multiple language ecosystems and a lot of the alternatives simply don't have that or enough of a community of users that care enough to fix that. People have their favorites but they can't seem to agree on a single one. So, Markdown it is for most of us. I'm not even sure that is a bad thing.

I kind of like it, actually. It's good enough for my needs. I use pandoc to convert markdown files to html for my website. It supports enough of the Github dialect that I don't have to obsess over what it supports or doesn't support too much. I'm unlikely to convert my content to another format at this point. I use it without thinking in Github issues, in readme's, etc.

Re: Thoughts on Markdown

#34

Earlier quoted context omitted.

Using Markdown with pandoc and pandoc-crossref is basically perfect as a substitute of LaTeX. It allows in-line and standalone LaTeX, and citations with crossref.

In my experience this has zero advantage over LaTeX since converting your markdown to formats other than LaTeX will be just as hard as converting from a LaTeX source. It's even harder because you have to deal with an eclectic mix of LaTeX and markdown, and various errors and restrictions in pandoc.

yes, these are all fraught. Any X-to-Y format exchange is a brew/apt miracle in my experience. It's not necessarily important for a LaTeX document to be render-able in all media, but the maths disciplines, for example, should be asking themselves how they want to be able to search for things including formula, algorithms etc, and finding ways to guarantee that a maxima of media support search/find/read operations on their articles. It's not just about how easy is it to input? but it's very similar to "how easy is it to get back out?" it has been a bit of a mismatch in maths re formulae expressions, and how those are represented visually vs. textually.

Re: Thoughts on Markdown

#35

Earlier quoted context omitted.

The problem is not writing or reading LaTeX, properly written LaTeX is very readable. It's easy to maintain and understand, and Bibtex for bibliographies works fine once you've gotten used to it. The problems start once you have to convert this to MS Word, which is essentially impossible with any advanced LaTeX document which will invariably contain complex formulas and also include hacks and adjustments in the pream…

You're right: LaTeX is very readable. I've never understood the complaints about the system. What's so hard about writing `\section{Introduction}` or `$R \int_0^1 f dx$`? After a bit of learning on your first document (perhaps requiring half the time of one of the first of dozens of edits you'll be making, if the document is important), what you get is (a) ease of transition between formats (article in journal become…

The biggest misunderstandings about LaTeX stems from comparing it with Microsoft Word or to any other word processor. LaTeX is a typesetter. You give the text, the template and the page size and it typesets it all. You nudge it with hints, and that's all. So, LaTeX is content first and layout second in a sense.

On the other hand, word processors work at absolute terms, layout first. Looking to LaTeX from this perspective distorts the vision a lot, and people get confused.

When one understands the idea of "LaTeX gets the content and fits to the constraints at hand", the rest is liberating.

Re: Thoughts on Markdown

#36
>That’s almost 20 years ago — yikes! What started as a more writer- and reader-friendly syntax for HTML

The author appears to have some recency bias that misses the point of Markdown. It didn't start when it was named and mapped to HTML. It was in use on usenet and in emails before HTML even existed. And most of its conventions came from typewriters before that.

You could print out a Markdown document today and jump in a time machine to 1970 and hand it to someone and they'd understand it. Chances are they still will in 2070.

In the meantime we've had countless proprietary binary word processor formats that couldn't be read before their program was released and most of which can't be read today. We've had bad attempts to replicate print publishing designs and unusable Flash websites. We've had a variety of markup formats including HTML, XML, etc. which are relatively a pain to read or write. We've had lousy WYSIWYG editors that never work correctly. And we've stored the documents split into chunks in databases. And now the suggestion is to write text as JSON data structures?

All that stuff has its place, but none of it has the timelessness and clarity of plain text and markdown when it comes to documents.

It's not particularly good for structured data. Nor multimedia (though you can reference it with links). But it's still quite good at what it is good at. Has been since before HTML and will be long into the future.

Re: Thoughts on Markdown

#37

Earlier quoted context omitted.

The problem is not writing or reading LaTeX, properly written LaTeX is very readable. It's easy to maintain and understand, and Bibtex for bibliographies works fine once you've gotten used to it. The problems start once you have to convert this to MS Word, which is essentially impossible with any advanced LaTeX document which will invariably contain complex formulas and also include hacks and adjustments in the pream…

You're right: LaTeX is very readable. I've never understood the complaints about the system. What's so hard about writing `\section{Introduction}` or `$R \int_0^1 f dx$`? After a bit of learning on your first document (perhaps requiring half the time of one of the first of dozens of edits you'll be making, if the document is important), what you get is (a) ease of transition between formats (article in journal become…

I genuinely can’t tell if you’re being sarcastic.

Re: Thoughts on Markdown

#38

Markdown is merely the lowest common denominator of what is essentially a jungle of weird and wonderful wiki languages. The reason it is so under-specified is that it emerged out of the Ruby community in a time where the whole point of Ruby was that it was a scripting language without a lot of appreciation for things like types or specifications. The first serious attempts to unit test and specify ruby itself actuall…

John Gruber’s original markdown processor was written in Perl, not Ruby.

Re: Thoughts on Markdown

#39

The discussion reminds me a little of the one around LaTeX in the scientific community. Latex is extremely powerful but reading the raw source of a text is a pain. WISYWIG is just so much more comfortable when writing, but MS Word sucks in its own specific and manifold ways (as does LibreOffice). HTML is still not nice to read, too much boilerplate tags required. Markdown source however is mostly well-readable in a p…

> Latex is extremely powerful but reading the raw source of a text is a pain.

For the kind of text that you'd use Markdown for, i.e. text that is mostly just text and not math heavy, LaTeX should be almost as readable as Markdown. For example,

    \section{Introduction}
is almost as readable as

    ## Introduction

Re: Thoughts on Markdown

#40

Earlier quoted context omitted.

You're right: LaTeX is very readable. I've never understood the complaints about the system. What's so hard about writing `\section{Introduction}` or `$R \int_0^1 f dx$`? After a bit of learning on your first document (perhaps requiring half the time of one of the first of dozens of edits you'll be making, if the document is important), what you get is (a) ease of transition between formats (article in journal become…

The biggest misunderstandings about LaTeX stems from comparing it with Microsoft Word or to any other word processor. LaTeX is a typesetter. You give the text, the template and the page size and it typesets it all. You nudge it with hints, and that's all. So, LaTeX is content first and layout second in a sense. On the other hand, word processors work at absolute terms, layout first. Looking to LaTeX from this perspec…

> "LaTeX gets the content and fits to the constraints at hand"

I'll believe this when scientific papers start appearing in the form of reflowable HTML.

Post reply on HN