7 ms·

Nice writeup. I'm currently writing a (technical) book in markdown, and I know I am going to pay for it later, but I don't care because I'm able to write quick

Nice writeup. I'm currently writing a (technical) book in markdown, and I know I am going to pay for it later, but I don't care because I'm able to write quickly without anything getting in the way. I'm able to use git to commit changes and a host of tools to preview the work. Also, using markdown now will force me to edit it again when putting a final version together for a real editor. For the skeptics: I don't see how using markdown is any worse than using a typewriter. Its an interim medium that allows for quick capture of structure and thought.

rando444 10y ago
I think most of the skeptics are just people that need/expect to have "feature x" that they have a personal preference for. For others, simplicity is preferable. George R.R. Martin does all of his writing in WordStar 4 on a DOS machine, which is a good example of not needing the fanciest tools to be highly successful.
geerlingguy 10y ago
If you use LeanPub, you can fully publish both ebook and paperback versions from the Markdown source. And for editing, if you have an editor who's willing to not use Word, you can use a tool like Authorea to track changes, and then incorporate those back into the markdown source. I really don't get the hate on Markdown; it's IMO the fastest way to get words from brain into text, more so than rST and other formats, because of its simplicity. And for slightly more involved formatting, with LeanPub, you can put down what you need, then fix formatting by previewing the published copy until it looks just right.
- binarymax 10y ago
  Thanks for the tip! I had briefly seen LeanPub before when I was just starting out writing in the winter. I will give it a closer look, since I remember having a good impression.
- lkiux 10y ago
  I never understood this argument about rST. The syntax for the same MD features in rST is only /marginally/ different, certainly not harder. I use both, depending on the context (which forces me to use one or the other). Most of the time you don't even notice the difference, because both have a really good baseline. However MD falls short for writing technical documentation, which is why pretty much anyone has to dope the "standard" (GH flavored MD, and so on). The syntax for the extensions is not any better than what rST offers. rST generally allows a more human-readable writing style, whereas MD with extensions has a lot of very verbose inline formatting. In fact, rST CAN have a slight edge in my mind as a human readable document if you use the appropriate formatting, whereas MD with extensions is easier for a program to parse. But, I repeat myself, for the same set of MD features, rST is hardly different. If you don't believe this, use pandoc and try to transform a vanilla MD document into rST. Now pick any rST page from sphinx documentation, and move back to MD. Hardly any better. sphinx is often criticized for being "hard to write" or illegible, transferring the blame to rST, but for the same set of formatting MD is not better. sphinx allows a whole slew of extra features which require a lot of annotation, and MD doesn't save the day. What's really annoying if having to switch between the two. We have projects which have a good majority of text documents written in MD and then API references in rST. I hate that. There's constant mismatch. Just pick one :(
wangchow 10y ago
Check our this guide on using ReStructured text with emacs. Great tutorial here. https://www.masteringemacs.org/article/how-to-write-a-book-in-emacs https://www.masteringemacs.org/article/how-to-write-a-book-i...
aidenn0 10y ago
MD isn't much worse than a typewriter, but it's not a whole lot better either. There are all sorts of things one wants to do with technical documentation that either isn't possible or isn't very easy with markdown. For most prose it's fine, and there certainly isn't any downside to using it versus any other lightweight markup format for drafts of technical documentation.
- mveety 10y ago
  I agree completely about MD and don't see why choose that troff other than that it's the new hotness. Troff can be dumb and simple like MD which is fantastic for the writing bit, but has the ability to do rather complicated formatting if you need that. There are macro sets other than man and ms like mom that add features or make the syntax clearer. Most troff implementations are able to output or have tools to output to various formats like ps, pdf, text with control codes, plain text, etc. Plus, on most systems, either groff, heirloom troff, or Plan 9 troff is there by default. It makes a lot of sense to me because of its potential power and the portability of it.
  - aidenn0 10y ago
    If you can't see why people prefer the first to the second, I don't know what else to tell you Markdown: An h1 header ============ Paragraphs are separated by a blank line. 2nd paragraph. *Italic*, **bold**, and `monospace`. Itemized lists look like: * this one * that one * the other one troff -ms: .NH An h1 header .LP Paragraphs are separated by a blank line. .PP 2nd paragraph. *\FIItalic\F[], \FBbold\F[], and \F(CRmonospace\F[]. Itemized lists look like: .IP \[bu] this one .IP \[bu] that one .IP \[bu] the other one
adamhyde 10y ago
"I don't see how using markdown is any worse than using a typewriter."...errrr...i think we have moved past the typewriter somewhat

rando444 10y ago

I think most of the skeptics are just people that need/expect to have "feature x" that they have a personal preference for. For others, simplicity is preferable. George R.R. Martin does all of his writing in WordStar 4 on a DOS machine, which is a good example of not needing the fanciest tools to be highly successful.

geerlingguy 10y ago

If you use LeanPub, you can fully publish both ebook and paperback versions from the Markdown source. And for editing, if you have an editor who's willing to not use Word, you can use a tool like Authorea to track changes, and then incorporate those back into the markdown source. I really don't get the hate on Markdown; it's IMO the fastest way to get words from brain into text, more so than rST and other formats, because of its simplicity. And for slightly more involved formatting, with LeanPub, you can put down what you need, then fix formatting by previewing the published copy until it looks just right.

binarymax 10y ago
Thanks for the tip! I had briefly seen LeanPub before when I was just starting out writing in the winter. I will give it a closer look, since I remember having a good impression.
lkiux 10y ago
I never understood this argument about rST. The syntax for the same MD features in rST is only /marginally/ different, certainly not harder. I use both, depending on the context (which forces me to use one or the other). Most of the time you don't even notice the difference, because both have a really good baseline. However MD falls short for writing technical documentation, which is why pretty much anyone has to dope the "standard" (GH flavored MD, and so on). The syntax for the extensions is not any better than what rST offers. rST generally allows a more human-readable writing style, whereas MD with extensions has a lot of very verbose inline formatting. In fact, rST CAN have a slight edge in my mind as a human readable document if you use the appropriate formatting, whereas MD with extensions is easier for a program to parse. But, I repeat myself, for the same set of MD features, rST is hardly different. If you don't believe this, use pandoc and try to transform a vanilla MD document into rST. Now pick any rST page from sphinx documentation, and move back to MD. Hardly any better. sphinx is often criticized for being "hard to write" or illegible, transferring the blame to rST, but for the same set of formatting MD is not better. sphinx allows a whole slew of extra features which require a lot of annotation, and MD doesn't save the day. What's really annoying if having to switch between the two. We have projects which have a good majority of text documents written in MD and then API references in rST. I hate that. There's constant mismatch. Just pick one :(

wangchow 10y ago

Check our this guide on using ReStructured text with emacs. Great tutorial here. https://www.masteringemacs.org/article/how-to-write-a-book-in-emacs https://www.masteringemacs.org/article/how-to-write-a-book-i...

aidenn0 10y ago

MD isn't much worse than a typewriter, but it's not a whole lot better either. There are all sorts of things one wants to do with technical documentation that either isn't possible or isn't very easy with markdown. For most prose it's fine, and there certainly isn't any downside to using it versus any other lightweight markup format for drafts of technical documentation.

mveety 10y ago
I agree completely about MD and don't see why choose that troff other than that it's the new hotness. Troff can be dumb and simple like MD which is fantastic for the writing bit, but has the ability to do rather complicated formatting if you need that. There are macro sets other than man and ms like mom that add features or make the syntax clearer. Most troff implementations are able to output or have tools to output to various formats like ps, pdf, text with control codes, plain text, etc. Plus, on most systems, either groff, heirloom troff, or Plan 9 troff is there by default. It makes a lot of sense to me because of its potential power and the portability of it.
- aidenn0 10y ago
  If you can't see why people prefer the first to the second, I don't know what else to tell you Markdown: An h1 header ============ Paragraphs are separated by a blank line. 2nd paragraph. *Italic*, **bold**, and `monospace`. Itemized lists look like: * this one * that one * the other one troff -ms: .NH An h1 header .LP Paragraphs are separated by a blank line. .PP 2nd paragraph. *\FIItalic\F[], \FBbold\F[], and \F(CRmonospace\F[]. Itemized lists look like: .IP \[bu] this one .IP \[bu] that one .IP \[bu] the other one

adamhyde 10y ago

"I don't see how using markdown is any worse than using a typewriter."...errrr...i think we have moved past the typewriter somewhat