Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Markdown is holding you back

newsletter.bphogan.com

Post reply on HN
Print view View original

131–140 of 194 posts

Re: Markdown is holding you back

#131

Post by hysan »

bccdee wrote: post #120
hysan wrote: post #61

Earlier quoted context omitted.

The author addresses this too. Once you start down this path, you go down the road of non-standardization which means losing portability, etc. I don’t see how this is a point against the author?

None of the author's other suggestions are portable either. So what if pandoc markdown is only understood by pandoc's tooling? DocBook is only understood by DocBook tooling. The difference is that pandoc markdown is already 95% similar to every other flavour of markdown, so migrating to a new system (if necessary) would be relatively simple. Also, the difference is that XML is a pain to write and I'm not sure semanti…

Maybe portable isn’t the right word. I read portable as meaning the format’s semantics are consistent across platforms. The way I read the author’s complaint was that once you start tacking on extensions to markdown, you run into the problem of seeing if other markdown platforms being able to support your variant of markdown. Hence the part about CommonMark vs GitHub-Flavored Markdown vs etc. Having actually run into this before when working on CMSes in the past, I get why the author sees this as a problem. I don’t think everyone will agree with the authors viewpoint, but I just happened to think that this thread is completely missing the point that the author is trying to make.

Re: Markdown is holding you back

#132

Post by coffeefirst »

jillesvangurp wrote: post #93

The main point of Markdown is that it has a very important feature that other languages don't have: it's supported in a lot of places. Most of the alternatives mentioned in this thread or in the article are things that require custom tools, that can't be used in most of the places that currently do support markdown. It's common in a lot of places. Even Google Docs has a well hidden feature that allows you to paste ma…

The other major feature is anyone can learn it in 5 minutes and fit all the instructions on an index card.

Many years ago I introduced it at a newspaper full of OG reporters who were a little nostalgic for the clatter of typewriters and the kid who would run the drafts around the newsroom.

On the first day they thought it was weird. On the second—and I'm not exaggerating, it was 24 hours—they loved it, because unlike MS Word/most WYSIWYG junkers, it did exactly what they told it to, without fussy formatting or invisible characters.

I've done this several times since, with all kinds of non-technical users who would never, ever tolerate something like LaTeX.

Re: Markdown is holding you back

#133

Post by flohofwoe »

immibis wrote: post #118
flohofwoe wrote: post #105

Eh, we had plenty of such structured document formats in the past. Markdown has won simply because it's much less hassle to write while still being readable without a specialized viewer. Markdown is exactly at the right sweetspot.

As long as your unstructured hassle-free writing just happens to be in the same format accepted by the viewer.

A generic ASCII capable text viewer is enough to read markdown, that's the point ;)

Re: Markdown is holding you back

#134

Post by catlifeonmars »

judahmeek wrote: post #91
vidarh wrote: post #34

Earlier quoted context omitted.

While that's true, I'd take Markdown + extensions to allow inline HTML or custom tags over AsciiDoc any day, even at the cost of losing some compatibility - converting that to plain Markdown is usually easy enough.

What are the trade-offs with AsciiDoc that would make you choose Markdown instead?

Not op, but markdown is much more likely to render well in different contexts, without post processing. My editor understands markdown, GitHub understands markdown, the link preview renderer in understands markdown. It’s the lowest common denominator

Re: Markdown is holding you back

#135

Post by [deleted] »

zelphirkalt wrote: post #119
jillesvangurp wrote: post #93

The main point of Markdown is that it has a very important feature that other languages don't have: it's supported in a lot of places. Most of the alternatives mentioned in this thread or in the article are things that require custom tools, that can't be used in most of the places that currently do support markdown. It's common in a lot of places. Even Google Docs has a well hidden feature that allows you to paste ma…

While it is true, that Markdown is available in more places, it is also true, that it as well "requires custom tools". Just that those tools already got put in place by people developing things. There is no technical reason keeping developers from supporting other languages as well. It's more of a social issue, that they don't. I also doubt, that Markdown will be able to be extended with the same "ease" HTML has been…

[deleted]

Re: Markdown is holding you back

#136

Post by [deleted] »

littlestymaar wrote: post #92
dschuessler wrote: post #10

You can include arbitrary HTML tags in Markdown at any place you need them.[0] I am not aware of any Markdown tooling that does not support this. So, no, Markdown is not holding me back. It is perfectly capable of what the author claims it isn't. [0]: https://daringfireball.net/projects/markdown/syntax#html

> I am not aware of any Markdown tooling that does not support this. Reddit surely doesn't, and I'd be very surprised if github did. In practice, in any place you want untrusted users writing markdown stuff for formatting, you cannot allow arbitrary HTML for security reasons.

[deleted]

Re: Markdown is holding you back

#137

Post by [deleted] »

dardeaup wrote: post #18

This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?

[deleted]

Re: Markdown is holding you back

#138

Post by meonkeys »

dardeaup wrote: post #18

This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?

I wouldn't use Markdown for that.

You're right to start with your requirements. Try to get detailed, like the list @WA wrote out, then match it up with appropriate tech.

I wrote a technical book and I also wanted multiple decent-looking outputs. In my case: HTML, EPUB/mobi, screen and print PDFs. I was struggling with Markdown+pandoc+custom scripts/styles, so I switched to Asciidoc. I wrote about that process here: https://adammonsen.com/post/2122/

Most of the formats came out satisfactory, but there were some gotchas. https://github.com/meonkeys/shb/#%EF%B8%8F-book-formats lists some, and https://github.com/meonkeys/shb/blob/main/issues.adoc has more. Translating from English to German went OK with asciidoc, but it might have been better with docbook and standard translation tools for working with .po files.

Here are two examples where the author used Markdown and the result was beautiful and successful (although layout for printed editions were done with extra/other tooling): http://gameprogrammingpatterns.com , http://www.craftinginterpreters.com . I'm curious if Bob would/will use Markdown for his next book. My process is different than Bob's... I didn't need literate code and I didn't want to do _any_ layout/pre/post-processing, even for print. Asciidoctor worked for this, although there were some compromises (see my links above). Print-ready layout is a lot of work, however you do it.

Is this your first book? Do you have a publisher? Will it be printed on paper? Do you have a developmental editor / proofreader / etc? Do you have a plan for what you'll do after you publish e.g. talks/promos/tour?

Contact me if you want to chat. I'm happy to share my war stories. And good luck!

Re: Markdown is holding you back

#139

Post by otterley »

zelphirkalt wrote: post #124

The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format. Markup formats in my opinion need to be defined in terms of a proper grammar, so that we can easily adapt that grammar in any programming language to build a parser and have support for that format in another language. The Org format in Emacs also suffered from this, but now there is an effort to…

> The problem with reStructuredText at least is, that there seems to be only one canonical parser, that defines the format.

The same is true of Markdown (the canonical parser being John Gruber's at https://daringfireball.net/projects/markdown/) but that didn't stop third parties from extending it in their own implementations. For example, canonical Markdown doesn't support tables at all, but GitHub added custom markup for tables to their parser ("GitHub-flavored Markdown") and it became a de facto standard.

Re: Markdown is holding you back

#140

Post by a3w »

dschuessler wrote: post #10

You can include arbitrary HTML tags in Markdown at any place you need them.[0] I am not aware of any Markdown tooling that does not support this. So, no, Markdown is not holding me back. It is perfectly capable of what the author claims it isn't. [0]: https://daringfireball.net/projects/markdown/syntax#html

I also used pandoc and markdown, and never bothered going back to ascidoc, full HTML, or latex.

Footnotes are the only not always included extension to mmarkdown I need for slides or argument flows that are not killed by sidenotes, and some sites and toolings support that in markdown.

Even table of contents is not a problem, so what else is left? Formula setting? Buttons for UI vs function? Buttons plus Inline JS for step by step state modification?

I am not programming, I want text and something to be easily pasted into Word-like rich text, which seems to be the default text editor for emails for 90% of the population.

Post reply on HN