Ask Slashdot: Do You Use Markdown and Pandoc?

BartlebyScrivener writes "I am a author, screenwriter, law prof, and a hobbyist programmer. I love MacVim and write almost everything in it: Exams, novels, even screenplays now that Fountain is available. I use LaTeX and WordPress and so on, but several years ago I discovered Markdown and the wonderful Pandoc. I searched Slashdot expecting to find lively discussions of both Markdown and Pandoc, but found nothing. Do Slashdotters look down their noses at these tools and do their work in HTML and LaTeX? I can't imagine computer geeks using Word instead of their favorite text editors. If not Markdown and Pandoc, what tools do Slashdotters use when they create documents that probably need to be distributed in more than one format: HTML, PDF, EPUB or perhaps even docx?" And then there's DocBook, LyX, and a host of other markup languages. What do you use, in what context?

Comments

I use

[Anonymous Coward]

reStructuredText. It is a lot more powerful than Markdown while still maintaining beauty. It is a bit more strict with formatting though, as is always the tradeoff for more power.

Yes

[Ardeaem]

I used to use LaTeX for everything, but I have switched to markdown for presentations, papers, tech reports, and even everyday statistical analysis (probably, they'll turn into tech reports anyway). LaTeX is way too finicky for everyday use. markdown doesn't completely fail over a misplaced character, while LaTeX will. Of course, you're giving up a lot of power by moving to markdown, but I find for most things markdown provides a good balance of usability and flexibility. I still use LaTeX for papers I'm going to submit to scientific journals, which is where I need the features of LaTeX.

I use the Rmarkdown flavor of markdown.

Markdown is gaining popularity again

[tomer]

Markdown is gaining popularity again thanks to the environment and community around GitHub. That said, I afraid that most people still would prefer wysiwyg systems, as it easier to use than 'feel like a programmer' when using weird codes such as HTML, MarkDown, bbcodes, MediaWiki etc.

Re:Markdown is gaining popularity again

[gd2shoe]

That said, I afraid that most people still would prefer wysiwyg systems, as it easier to use than 'feel like a programmer' when using weird codes such as HTML, MarkDown, bbcodes, MediaWiki etc.

"Feel like a programmer" isn't the problem. Knowing that something is technically correct, but being unable to instantly verify that it is aesthetically pleasing is a major hangup. Unless you're making a professional report, or writing a book, there's no benefit to: hand-encoding a text, rendering it, editing the code, re-rendering it, tweaking the code, re-re-rendering it, tweaking the code again, re-re-re-rendering it... ad infinitum. In order for all that work to be worth it, the project must call for absolute perfection.

For a vast majority of writings out there, "good enough" is good enough.

(In today's day there really is no good reason why we can't have LaTeX quality wysiwyg. Computationally expensive, blah, blah, blah. We've got very, very fast computers on every desk today. Caching, and clever use of pre-rendering would permit a vast majority of changes to be rendered in real-time.)

Re:Markdown is gaining popularity again

[djmurdoch]

I think the problem with wysiwyg is that it is not "what you see is what you mean". LaTeX rendering only works because the code says what you mean. It is very, very hard to design a wysiwyg editor that forces you to type what you mean, instead of what you think you want it to look like.

Any LaTeX user who has co-authored something with a Scientific Word user knows this: the LaTeX it outputs is nonsensical, but it looks sort of okay when rendered. Just not as good as LaTeX from someone who speaks it as a native.

Re:Markdown is gaining popularity again

[gnapster]

Have you ever used TeXmacs, and do you have an opinion of it? I suspect you have, since "what you see is what you mean" is a phrase of which they are quite fond.

For those who have not: TeXmacs is a graphical editor which implements the typesetting rules from TeX in an editor whose interface is inspired by emacs. (M-x commands, and all.) It does not use LaTeX as an intermediate rendering engine. I used it for a while. It has some virtue.

Re:Markdown is gaining popularity again

[TheRaven64]

You can fix it, but I agree that it usually puts it in the worst possible place. The problem is that TeX uses an elegant dynamic programming model to determine where to break lines in a paragraph, but uses a greedy algorithm to do page layout. Why? Because the PDP-10 didn't have enough RAM for the dynamic programming tables that would be required to do elegant page layout on a typical document. On a modern computer, even if it takes 2-3MB for the tables, you most likely have a single image in the document that is bigger than that (in early TeX, images had to be added afterwards in a separate compositing phase after you sent the typeset document to the printer, because computers weren't powerful enough to handle nontrivial images).

I tried implementing the TeX linebreaking algorithm for page layout in some naive (unoptimised) Objective-C a few years ago and ran it on a 900-page book that I'd written. Even then, it took under a second to run on the laptop I had at the time. There's no reason not to do it now.

Re:Markdown is gaining popularity again

[TheRaven64]

WYSIWYG is a terrible way of writing, but it's a great way of editing. The problem is that most modern tools conflate the two. When I write, I prefer to use vim and minimise the distractions - I see the words, I focus on the words and the markup describing their meaning, and I worry about the typesetting later. For articles, actually I don't worry about the formatting at all, my publisher sorts all of that out and so there's no reason for me to bother. I don't care what it looks like - that's not my job as a writer - I care that it's coherent and fluid prose. For books, I use LaTeX, and then I typically have a few rounds of iterations at the end of each chapter when I do the tweak-recompile-check cycle. I structure my environment such that I can build each chapter independently, which speeds up the build times, but it's still painful getting the style tweaks in correctly. I'd be much happier if I could get LaTeX to do a first formatting pass and then use a visual WYSIWYG editor to tweak everything and have those changes preserved the next time I do a formatting run from the source text.

favorites...

[excelsior_gr]

I can't imagine computer geeks using Word instead of their favorite text editors.

Indeed, everyone has his favorites. People have argued text editors to death. Find what works for you and use it (and stop flaming us). Also, programmers write software, not documentation. All document conversions are left to the secretary (and she may do it in any way she pleases).

WYSIWYM vs. WYSIWYG and other axis

[jbolden]

I think you have a bunch of axis going on here at the same time.
1) Open source tools vs. closed source
2) General use vs. specialized
3) WYSIWYM vs. WYSIWYG editing.

Let's start with (3). I generally like WYSIWYM more than WYSIWYG environments. That being said WYSIWYG is very useful for content where consistency doesn't matter as much. While there are WYSIWYM systems for presentations but they only really work for data publishing better than WYSIWYG. I think a fairer comparison on this axis might be LyX vs. Word or FrameMarker vs. Word. Going up something like higher end composition engines vs. something like InDesign.

Then there is general use vs specialized. LaTeX is optimized for text with equations which is specialized. Fountain is for screenplays. That's not the same as a product like Word which is all purpose.

Finally open source vs. closed source is a complicating factor. When we consider Word do we consider all the myriad additional cost extensions, for example SharePoint or just the core product? For OpenSource do we consider the entire platform and how these components work together? More importantly closed vs. open goes beyond editing to broader computing issues.

I use emacs

[foobar bazbot]

Because it has C-x M-c M-butterfly.

Re:Yes

[buchner.johannes]

LyX for reports and paper writing, with some raw LaTeX sprinkled in. I have a short python script that can merge multiple documents so I don't have extremely long bulks of content. And there is the python environment for LaTeX, which is awesome with sympy and matplotlib.
LibreOffice for quick documents perhaps with images for a quick WYSIWYG. There is no reason to do everything in text, for some (many?) things the feedback loop is just way too long.
reStructuredText for code documentation, anything that should be readable from command line, but also can be used to make pretty html websites. Sphinx helps. rst exports into plenty of formats via docutils (just expand for rst2* commands).
Converters to epub for stuff I want to read on my ebook reader (from Calibre).
For the text formats my usual editor is gedit. Simple and plain.

It doesn't matter much if you prefer Markdown or rst, that's like arguing which wiki has the best syntax. There are plenty of utilities that can cross-convert and export (pandoc is one of them).

Minutes

[hlub]

I use asciidoc as a quick and easy way to take minutes of meetings. I usualy mail the participants a quite decent-looking pdf version of the minutes immediately after the end of the meeting. I also use gitit as a personal wiki. I must admit that I sometimes confuse the syntax of the markdown used by gitit with the quite similar asciidoc. I could switch to pandoc for my minutes, of course, but the pdf produced by asciidoc looks a lot nicer than pandoc's

Scrivener

[Tridus]

If you're writing a novel, a tool like Scrivener is a lot better than a text editor of any particular sort. It's designed for writers and makes it easy to do things like keep track of and organize all your notes, which if you're writing a novel is going to be far more important than whatever command is used to change the font.

Re:"I am a author"

[93 Escort Wagon]

He didn't say he was a good author...

Re:markdown is great

[cr_nucleus]

A bit of search told me that it's actually Mou, not Moc.

Whatever floats your boat

[frisket]

I use Emacs for writing; most of it is in XML (usually DocBook, sometimes TEI, occasionally XHTML). I use XSLT to transform it to LaTeX if I want publication-quality PDF, but more often the document is the input to other people's toolchains which want XML first. I occasionally transform to other formats (HTML, Word, or some wiki formats which are largely MarkDown-ish).

I author in XML because most of what I write involves quite detailed and very specific structure, and DocBook and TEI provide appropriate levels of markup for this. I made a conscious decision to go this way a very long time ago, when it was all still SGML, and I have never regretted it.

Most people don't have that level of specificity to adhere to. All the formats you mention have their areas of application, even Word, but there is a growing undercurrent towards using HTML5 as the default format, driven partly by the fact that Ebooks use it. The publishing industry is very interested, as they hate and detest Word, and only use it because its change tracking is useful and it has usable style-editing, which OpenOffice and friends don't have (ie they have no style margin like Word). It was very clear at the XML SummerSchool last month that there is growing support for HTML5 in editing tools, and some new advances in editorial control (eg systems like Xopus, FidusWriter, and Poetica) mean there may even be a way to escape from Word :-)

--
Disclaimer: editor interfaces are my thesis topic; I have no connection with any of the above except the XML SummerSchool.

It has been a while...

[vikingpower]

...that any Slashdot posting opened up a new world to me. This is one of those - way too rare - postings. I use to write flat text, and hand that to secretaries or colleagues for formatting it into whatever they want or need: html, word, slides, whatever. Software documentation, to me, is generated javadoc - so basically html generated out of flat-text code comments. Of course I knew and know about the existence of LaTex et al.. Yet, as a software architect, I guess I have been, for decades, plain lazy. I simply write flat text in emacs or notepad++. Man, you opened up a universe to me !

Re:Yes

[TeknoHog]

LyX for reports and paper writing, with some raw LaTeX sprinkled in. I have a short python script that can merge multiple documents so I don't have extremely long bulks of content.

\input{file.tex} is your friend, it's basically the latex equivalent of the include statement in many languages. It's particularly nice if you have a simulation, gnuplot etc. generating a splash of latex that you want to integrate in the full paper.

Re:Yes

[Jeremiah Cornelius]

Markdown, Pandoc, and Vim/MacVim are my primary working tools for writing documentation.

I believed "Markdown and Pandoc" to be a work of 16th century French literature. By Alcofribas Nasier, is it not?

WYSIWYGs vs Markdown

[Dracos]

As a web developer, I understand the need to allow users to create content. However, I consider full blown web-based WYSIWYGs (such as TinyMCE and CK Editor) to be terrible tools. Yes, they take care of most of the dirty details, but they also have the capacity produce bloated garbage markup. I've always found bbCode annoying. I've used a couple of Wiki syntaxes as well (MediaWiki, Jira), and find them only slightly less annoying than bbCode. Because I know HTML, I prefer to just write HTML when I know the final format will be HTML.

Markdown syntax is clean, succinct, and can be extended when needed. The vast majority of non-savvy users only need to do basic formatting (bold, italics, headlines, lists) and Markdown covers that very well, in a way that the user can't do much damage to the prescribed styling of the content.

I've very briefly experimented with LaTEX, not enough to have actually used it for anything. I was not aware of PanDoc, but it looks very interesting.

Org mode

[PybusJ]

I like the emacs org mode (also available for vim, and even your mobile), though primarily for structured outlines/note-taking, its markup allows document formatting and it can export to a range of formats including PDF.

Notes, documents, TODOs, all in one format.

Re:Yes

[fyngyrz]

I wrote my own in Python; uses PostgreSQL to hold the data, gives me unlimited stylesheet and substitution capabilities, generates HTML or whatever I want directly. Table of contents, indexes in various formats, footnotes, endnotes (references), chaptering and sub-sectioning, local and global variables, image handling and conversions, etc. Works a charm. And since I wrote it, I can add to it, fix it, etc.

Here's an example of an output document:

SdrDx Manual

When I want to typeset something crazy, I do it in an image manipulation system and then shovel the image in; that's about the only thing I've run into that would require more work than I'm willing to put in.

Re:vi

[UnderCoverPenguin]

vi with Doxygen, since most of what I write is code. Also for other documents (yes, Doxygen is designed to extract markup from special comments, but it doesn't care if the input file is one block comment. Just start the file with /** and end with */). Makes sense to use the same tool.

FYI, Doxygen also understands some HTML and recently added a subset of Markdown. I use a few HTML and Markdown elements, usually for lists and tables.

For some documents, I use pure HTML, such as my resume. This gives me more control of the formatting. Also, MS Word understands HTML, so to provide a ".doc" file, I just make a copy with the .doc extension.

I have tried other tools, like LateX and Lyx, but Doxygen and HTML cover %99.9 of my needs. (Wold be nice if Doxygen supported reStructuredText and MediaWiki markups.)

(FWIW, I prefer MediaWiki markup over Markdown. My biggest complaint with Markdown as compared to MediaWiki is the link syntax and link handling. I think MediaWiki links are much better than Markdown links.)

Re:Yes

[fermion]

I use LaTeX(beamer class) when it makes sense, which is anything that is going to be production. It does require a level of discipline, but to me, the text based input and the precise output makes it worth any limitations. I use python script to output LaTex. Given that LaTex output to PDF is routine any past issues are past.

For other things, Openoffice does everything I need. When I need a certain kind of fancy presentation I use Keynote.

Re:Yes

[Will.Woodhull]

Since wiki syntax has been mentioned, I'll jump in.

I now use wikitext for nearly all my writing, usually using gedit as the editor. My writing does not require the level of formating that LaTeX and its ilk are capable of. A good portion of my writing is in collaboration with others, and I want to grow that percentage since the text is consistently better when more than one person is stirring the word pot.

I've used several wiki engines since about 2003. At the moment Dokuwiki is my favorite: it has good ACL security, it handles embedded images and files okay, and it produces clean HTML5 pages. Mostly it behaves like Markdown in the way it gets out of my way when I'm using a plaintext editor.

An advantage of Dokuwiki and wikitext is that the semi-wysiwyg browser editor allows wider collaboration and effective proof-reading, by persons who don't want to learn a mark-up language, even a simple one.

When I need to do a brochure, business card, or other authoring task which is more about presentation than writing, then I use other tools. Inkscape is good, and I have done posters and slides in Gimp with little effort. But that is more about publishing than writing.

Re:not about CPU limitations, it's about grep + Em

[gd2shoe]

LibreOffice has its uses, but you can't grep .odt files.

Depends on what you're doing. You can't use grep, specifically, but you can search by regular expression in LibreOffice.

(Actually, instead of "LaTeX quality wysiwyg", which sounds like you want software other than Latex, but which gives equal quality, you probably meant to say "wysiwyg LaTeX". If that's the case, I agree...

That's one way to slice it, but not the only way. I think publishing has an unhealthy relationship with LaTeX. Markup languages have come a long ways since 1980. Why are we so stuck on this one? Another language that is (1) more human readable (2) easier to machine parse (3) renders to equal or better quality (4) is wysiwyg friendly, should be quite possible.

Wysiwyg Markdown, and writing tools.

[real-modo]

If you want wysiwyg markdown: on Windows, check out texts.io. On linux, Uberwiter. On Mac... there are probably lots of options besides texts.

If you write fiction, or any book-length texts (a Ph. D. thesis or academic papers, frex), you owe it to yourself to check out Scrivener. It's available for OS X, Windows, and in beta for Linux. Closed software and charged for, but worth it.

ABSOLUTELY

[aussersterne]

As someone that writes a great deal both for online and offline distribution, I use markdown *extensively*.

It's fabulous for the grunt work of formatting: headers, italics, links. The rest can be done by tossing in HTML, XML, or whatever other markup code is needed. It's fabulously lightweight and fast and unobtrusive.

In fact, for all those "I wrote my dissertation in LaTeX, *sniff* *sniff*" people here on Slashdot, how about this:

I wrote my dissertation on an iPad 2, in Daedalus, in markdown, embedding HTML or other kinds of markup as necessary, then formatting it all in a final pass through a couple different parser/formatters. Sometimes the right tool for the job is the one that you have to think about the least—the one that stays out of your way—and for me, that's markdown+Daedalus.

(Yes, I'm prepared for the onslaught of accusers, ridiculers, and doubters here—prepared to ignore them.)

I use...

[ItsJustAPseudonym]

...jEdit or gVim for entry, pandoc for conversion, Firefox for viewing in HTML. I take notes in markdown during tech meetings. It"s scary-fast to create good looking notes.

Re:markdown is great

[mcfedr]

Its actually called Mou, sorry, its a markdown editor with instant rendered preview

Re:Yes

[K. S. Kyosuke]

In the past century, there was also this neat tool called Scribe which spawned a bunch of similar tools, such as Skribe, Scribble, and Exscribe. Essentially, a rather light-weight semantic markup (like Markdown etc.) but at the same time extensible and programmable (like TeX) in a sane language (unlike TeX) and with multiple backends (again, unlike TeX).

I wonder if there's a space in the lightweight markup space for a better markup than Markdown. That's what many people use, but it sure is limited, and not even the extensions themselves are extensible.

If you haven't done it yet, I also advise you to take a look at Pandoc and Asciidoc. These are rather complete tools that have some pretty neat functionality. (If you know them, perhaps this mention will be useful to someone else at least.)

Re:vi

[TheRaven64]

The flamebait mods are obviously from people who use the other editor.

Re:Yes

[Anonymous Coward]

\include{chapter} is even better, as it lets you do things like compile only a single chapter (but with correct page numbering and such) when you're working on something specific. \input is a lot more low-level.