top
toc
j->
btm
g-1
g+1
/\
\/
a brief introduction to z.m.l. by bowerbird intelligentleman you can "view source" for this document here: http://zenmagiclove.com/hnews/hnews111111111.zml table of contents a brief introduction to z.m.l. table of contents chapter 1 -- review paragraphs chapter 2 -- review sections chapter 3 -- text styling in your book chapter 4 -- images in your book chapter 5 -- linking in your book chapter 6 -- lists in your book chapter 7 -- tables in your book chapter 8 -- footnotes and endnotes chapter 9 -- hyphens and dashes chapter 10 -- hyphenation stinks chapter 11 -- the play is the thing chapter 12 -- two spaces after a sentence chapter 13 -- unlucky number 13 chapter 14 -- poetry and other silly things chapter 15 -- multi-purpose block-quotes chapter 16 -- epigraphs and epitaphs chapter 17 -- the notes section chapter 18 -- meta-data for this book stop with the silly stupid scrolling markdown considered harmful preface the screed the ugly the bad the good john macfarlane fletcher penney brett terpstra markdown's future a few more things light-markup systems restructured-text ascii-doc textile markdown's arrival markdown in public i.o.s. apps draftin dot com editorially ghost wordpress dillinger simplenote long-form light-markup leanpub scrivener texts.app textastic zen markup language summary chapter 1 review paragraphs separate paragraphs with a blank line. don't indent paragraphs with spaces or tabs. (indeed, don't use tabs anywhere.) chapter 2 review sections separate sections -- chapters in particular, but also front-matter sections, and so on -- with 4 blank lines above the section header and 2 blank lines below the section header. every section must have at least one header, but it can also have two headers if you like, such as "chapter 1" and "in the beginning". separate the two headers with 1 blank line. chapter 3 text styling in your book italicized words are indicated with underbars, one at the beginning and another at the end. the beginning one _must_ have white-space to its left; likewise, the closing one _must_ have white-space to its right. in a phrase, each word must have its own underscores. *bold* words are indicated with asterisks, subject to the same rules on white-space. this word will be in _italics._ this phrase _will_ _be_ _in_ _italics._ this word will be in *bold.* this phrase *will* *be* *bold.* chapter 4 images in your book to include an image in your book, just enter its u.r.l. http://z-m-l.com/go/alice/checking_watch.png "what is the use of a book," thought alice, "without pictures or conversation?" http://z-m-l.com/go/alice/alice_cramped.png chapter 5 linking in your book remember how, in chapter 2, we said that the table of contents should be hot-linked to the appropriate spots? that is one type of link you'll need. there are several other types as well. your system should also be able to make the jump to an internet site. most of the e-texts are quite old, so of course it's not like they have a bunch of internet url's in them; but every e-text will indeed contain a link to project gutenberg's website, so you must be able to execute links... quite often there are places in an e-text that reference other parts of the e-text. in these cases, it's nice to have a hotlink close to (or on) that reference point that transports the reader directly to the place that is being referenced; it is convenient. your system should facilitate such linking, preferably making it happen automatically. for instance, the beginning of this chapter has a reference to chapter 2. if a reader clicked on those words -- "chapter 2" -- they should automatically go to chapter 2. (and likewise with each of the references to "chapter 2" here in this paragraph too.) chapter 6 lists in your book use " * " at the start of a paragraph to make a list. * one * two * three * four * five * six * seven * i forget what 8 was for. * number 9, number 9... *** you can also use " o " to make a list. o one o two o three o four o five o six o seven o i forget what 8 was for. o number 9, number 9... *** you can also use " + " to make a list. + one + two + three + four + five + six + seven + i forget what 8 was for. + number 9, number 9... *** you can also use " - " to make a list. - one - two - three - four - five - six - seven - i forget what 8 was for. - number 9, number 9... *** you can also use " = " to make a list. = one = two = three = four = five = six = seven = i forget what 8 was for. = number 9, number 9... *** you can also use " x " to make a list. x one x two x three x four x five x six x seven x i forget what 8 was for. x number 9, number 9... *** sometimes you want a numbered list... here's an example of a unordered list that masquerades as a numbered list, with the number specifically included. x 1. one x 2. two x 3. three x 4. four x 5. five x 6. six x 7. seven x 8. i still forget what 8 was for. x 9. number 9, number 9... *** here's another "numbered list", again with the number specifically included, but we mix things up a bit, to show how to do non-sequential numbers. x 101. one x 202. two x 3. three x 4444. four x 55555. five x 6. six x 77. seven x 88. i still forget what 8 was for. x 9. number 9, number 9... *** here's another numbered list, except this time it's a plain html ordered list, so the browser does the numbering. # one # two # three # four # five # six # seven # i still forget what 8 was for. # number 9, number 9... *** here's another example of a list: o mercury o venus o earth o mars o jupiter o saturn o uranus o neptune o pluto *** here's another example of a plus-sign list: + mercury + venus + earth + mars + jupiter + saturn + uranus + neptune + pluto *** here's another example of a minus-sign list: - mercury - venus - earth - mars - jupiter - saturn - uranus - neptune - pluto *** here's another example of an equals-sign list: = mercury = venus = earth = mars = jupiter = saturn = uranus = neptune = pluto *** like poems, items in a list generally want to stick together on the same page, if possible. chapter 7 tables in your book you can have tables in your book. you can use multiple-spaces to separate the cells. | table 1 column 1 column 2 | | plain-text yes yes | | x.m.l. no yes | | html yes no | | .rtf no yes | | .pdf no no *** or you can use or-bars to separate the cells. | table 1 | column 1 | column 2 | | plain-text | yes | yes | | x.m.l. | no | yes | | html | yes | no | | .rtf | no | yes | | .pdf | no | no chapter 8 footnotes and endnotes your book can have footnotes.[1] for a footnote, place the footnote-referent in square brackets.[1a] note that there must be _no_ white-space to the left of the referent, but that there _must_ be whitespace to the right of it. this is just a dummy paragraph, to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them. this is another dummy paragraph, to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them. this is a third dummy paragraph, to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them. and a fourth dummy paragraph, to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them. here's dummy paragraph #5, to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them. this is a sixth dummy paragraph, to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them. and the seventh dummy paragraph, to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them. here's dummy paragraph #8, to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them. i hope 9 dummy paragraphs is enough to get some separation between the footnote referent up above and the actual footnote below, so you can see the jump when you click between the two of them.[5] [1] you can put the footnote right underneath the paragraph which contains it, or at the end of the chapter containing it, or in a section at the end of the book with all the other footnotes. chapter 9 hyphens and dashes use a double-dash -- like these here -- to get an em-dash in your .html output. it's best to put spaces around your double-dashes, or else they can sometimes cause word-wrap problems... don't use a single-dash - like this bad example - where you want an em-dash, or it will look _bad_. even http://medium.com and http://kottke.org make that mistake. it's rather embarrassing, eh? chapter 10 hyphenation stinks do not hyphenate your text. e-books don't need it. and you never know exactly how the text will reflow. chapter 11 the play is the thing jaguar auto-bolds the first word of a paragraph if it is followed with a colon. this is handy when you are doing the dialog for a play. dale: that's not what p.g. is all about. bowerbird: i think it's important to give people a good e-book experience. dale: that's your opinion. bowerbird: yes it is. steve: (weakly) i can't... dale: no it isn't. steve: (weakly) get a... bowerbird: is too. steve: (weakly) word in edgewise... dale: is not. lurkers: will you two cut it out? bowerbird: is so. dale: is not... fade to black.[4] chapter 12 two spaces after a sentence many typesetters set a little bit of extra space between sentences, so the separation is clear. i support that, as i think it makes it look nicer. now some people try to get this nicer look via the old typewriter-trick of putting 2 spaces at the end of a sentence. but that doesn't work when the text is turned to .html. and further, the extra spaces mess with our editing process, where we often search the text for 2-spaces, just to make sure we haven't inadvertently introduced extra spaces in unwanted places. so the best tactic to use these days is to put only one space after a sentence, and _hope_ browsers will soon support better typography. chapter 13 unlucky number 13 there is no 13th floor in most buildings. chapter 14 poetry and other silly things use a space in the first column to get centered lines. t.v. will eat you (a haiku by bowerbird intelligentleman) t.v. will eat you out of a satellite dish with a tuning fork use multiple spaces (5 or more, in a consistent number) to get a chunk that is both left-justified and indented. a haiku for you (by bowerbird intelligentleman) haiku have three lines and seventeen syllables five, seven, and five you can vary the spacing, as some poems like to do. six spaces at the start of this line 12 spaces at the start of this line six spaces at the start of this line 12 spaces at the start of this line six spaces at the start of this line 12 spaces at the start of this line six spaces at the start of this line 12 spaces at the start of this line you can even get downright fweaky! six spaces at the start of this line ten spaces at the start of this line 14 spaces at the start of this line 18 spaces at the start of this line 22 spaces at the start of this line 26 spaces at the start of this line 22 spaces at the start of this line 18 spaces at the start of this line 14 spaces at the start of this line ten spaces at the start of this line six spaces at the start of this line chapter 15 multi-purpose block-quotes you can get a blockquote like this. : four score and seven years ago, our : forefathers set forth upon this continent : a new nation, conceived in liberty and : dedicated to the proposition that : all men[2] are created equal. or like this: > four score and seven years ago, our > forefathers set forth upon this continent > a new nation, conceived in liberty and > dedicated to the proposition that > all men[3] are created equal. you should note that the first method (using the colon) rewraps the lines, and the second (using the right-angle-bracket) does not rewrap the lines. so use the one which meets your needs better in each case. chapter 16 epigraphs and epitaphs | l | c | r | ||| _there's_ _an_ _old_ _proverb_ | ||| _that_ _says_ _just_ _about_ | ||| _whatever_ _you_ _want_ _it_ _to..._ | ||| _--_ _slashdot_ | sometimes a chapter starts with a nice pithy quote, which is usually _italicized,_ and often right-justified. so you wanna be able to handle that kind of thing.[55] chapter 17 the notes section [1a] personally, i don't think we need to make a distinction between footnotes and endnotes any more, i believe that all the types of notes should be stored at the end of the file, like these notes, but i think the person should be able to _display_ them at the point of reference in the actual body of the text. therefore, they are actually a sort of hybrid between footnotes _and_ endnotes, combining the strengths and convenience of both types. [2] in later years, it was made clear that lincoln was referring to all "people", and not just men, that women are equally equal. [3] again, in later years, it was made clear lincoln was referring to all "people", and not just men, that women are equally equal. [4] this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. look, it even has a second paragraph! this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. oh no! a third paragraph. way too long! this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. this is a test footnote. because of that, it's going to go on and on and on. [5] this is another test footnote. but it will be short. [55] this is another test footnote. but it too will be short. chapter 18 meta-data for this book here's the meta-data... o title = a brief introduction to z.m.l. o author = bowerbird intelligentleman o purpose = a brief introduction to z.m.l. o markup = zen markup language (.zml) o isbn = urn:isbn:0000000000000 o publisher = jaguar(ps) o subject = a brief introduction to z.m.l. o rights = copyright 2013 -- all rights reserved stop with the silly stupid scrolling printed books have had pages for 5 centuries. but the advent of word-processors introduced scrollbars into the equation -- one long page. and when the web came along, it was hybrid. a website was composed of different pages, but each of those pages had a scrollbar on it. in general, early e-book apps used pages, naturally, as they were emulating p-books. but even there, there was some controversy. some people equated the text in an e-book with the text in a word-processor, and thus argued that scrollbars be employed instead. and indeed, the recent versions of "ibooks" -- apple's i.o.s. e-book viewer-program -- have included a scrollbar option for users. this issue of pages (also known as "cards") versus scrolling has at times been religious, proponents on both sides quite vociferous. i'm here to make peace between the sides. to be clear, i am a page proponent myself. i think paging makes reading much easier, and i can give lots of examples in support. but i believe in giving people the power to choose according to their own preferences; it doesn't hurt me a bit if you want to scroll. i even recognize that scrolling can even give some benefits which pagination can't offer, which means i think it'd be advantageous to offer people the ability to easily switch from one mode over to the other mode, on the fly. now, after years of mulling over the issue, and a little bit of javascript under my belt, i have come to see a resolution is possible. indeed, there's no real reason to juxtapose pagination _versus_ scrolling as opposites. it's actually rather easy to get the benefits of both, with neither camp being unhappy. markdown considered harmful preface ok, first of all, you know that the "considered harmful" expression is an exercise in silly titles, right?, just a bit of humorous hyperbole. and, as i have just demonstrated -- right in my opening paragraph -- i am a person who is quite willing -- eager? -- to state the obvious. so bear with me. because though i will be discussing a raft of very real problems with it, i still do not really think markdown could ever be "considered harmful". there are lots of problems with it, and it's development _is_ troubled. and i'm gonna be frank about that. but still, i _love_ markdown. a lot! and if you don't, we'll have to fight. in particular, if you are one of those meatheads saying "markdown sucks, and i don't understand why people can't just write in .html, like i do", and you came for a spiel which you expected would validate your opinion, then you'll want to stop reading now, as i have no tolerance for such idiocy. any writer worth his or her salt knows that writing is hard enough, _without_ dodging all that brackets-and-tags crap in your text, disrupting your thoughts, every less-than-sign and ampersand nothing more than another distraction. so if you've somehow learned to ignore garbage strewn about your living-room, well, good for you, meathead, but that doesn't mean that now everyone else has to tolerate it in our living-rooms. so just walk away now, while you can, so i don't have to ridicule you further. because i love markdown. and, later, i will explain why, in detail, with some history and some analysis. but hey, i know you internet kids. i used a "considered harmful" title, and you jumped on that link-bait, so the last thing i can do now is to bait-and-switch by making you first sit through some history lesson or wallow through reasoned discourse. no sir, you came for a screed, and if i do not give it to you, _now,_ you might take it out on me, i know. indeed, you probably already think that this is getting too long-winded. so, if you're one of _those_ people, here's your meaty list of shit, quick!, for your tl;dr attention-deficit mindset. the screed here's "the good, the bad, and the ugly", in _reverse_ order, to end on a positive where i can continue on from that point to embark on a more thoughtful review. reflective readers can stay and think. and the accident-lurkers among you can speed off to seek your next thrill. the ugly for the truly ugly parts of markdown, we'll need to start at the very outset. gruber's original spec for markdown is _too_ _primitive_ for today's .html needs. to give just one little example of that, it doesn't automatically formulate the id tags needed on headers in order to have internal links in a document _or_ to allow deep-linking from the outside. given the web of today, that would be something that made it a non-starter. heck, even in the web of 2003, that _should_ have made it a non-starter. there are other omissions like that too. moreover, extensive usage showed us "classic" markdown is plagued by more than its fair share of "ambiguities" in the features which are included, because it's insufficiently complete. and last but not least, there are too many inconsistent "edge-cases", where the spec contradicts itself. of course, what can you expect from a perl script filled with reg-ex crap, which has seen one (count 'em -- 1!) update in 10 years? yep, exactly that. so first, it doesn't do _enough_ stuff. second, it's too silent on stuff it does, when it should be explaining it clearly. and third, even when it does explain, inconsistent edge cases soon pop up. putting it starkly, gruber-markdown simply ain't sufficient for prime-time. it has just got too many shortcomings. i mean, fine, if all you're using it for is the comments on your web-site, or to write your 3-paragraph blog posts; these shortcomings will not bother you. but once you are doing real documents, you will experience the burn, you will. because the gruber-classic is _lame._ to realize this is what people _mean_ with generic references to "markdown" is enough to make you cry in despair. whenever i hear someone say "markdown" to describe what they used for a text, and they don't name a specific flavor, when i know they've clearly used one, because generic markdown just cannot do the type of stuff they have done, it reminds me of relatives having web problems, so i ask them which browser they're in, and they say "the internet". the fact that few people know about the gruber-markdown shortcomings, or the wide variety of extensions, is because they use markdown only in the most very superficial of ways. (this is also why you hear them repeat the lie that "it only takes 5 minutes to learn all about markdown"; yeah, right.) and gruber has reinforced this notion that "markdown" is a superficial tool, insisting that, as far as he's concerned, gruber-markdown is a finished product. um, gee, ok, it might well be "finished", but it's nonetheless _badly_ _incomplete._ far too primitive for what we need today. the bad even if it's "good enough for gruber", the rest of the world has needs which often go beyond the mere superficial, so classic-markdown is _not_ "enough". plus it's only natural that people will improve any tool to get what they need. the first wave of people to embrace markdown use was comprised by coders who simply ported gruber's perl script to their particular language compiler, be it php, python, ruby, or whatever. but these individual developers also "extended" markdown, to improve on it -- for their own use and viewpoint -- by addressing its shortcomings, and were usually fairly successful at it. it's typically quite easy enough to invent a light-markup rule that will accomplish the outcome that you want. some of them added just a couple things. others put in a full range of new stuff. each person invented their own "flavor". every developer solved a different set of problems, and did it a different way. soon the various reformulations grew terribly out-of-sync with one another. the flavors clashed. they clashed badly. not only did they do different things in different ways, they often did the same thing different ways, and different things in the same way. so, total chaos. for a long time, few people noticed it, and even fewer minded. but as needs to transport markdown files from one system into another started to become common, these incompatibilities grew bothersome. so they became difficult to ignore, and thus began to be grudgingly acknowledged, then recognized as serious, until finally, they were finally noted across the board by everybody with extensive experience. so while developers plugged big holes in gruber's too-primitive classic-markdown, they have also exacerbated problems with the inconsistencies, to the degree that nobody is certain what "markdown" does now. so, if you feel that you have a certainty, you should prepare yourself for the shock -- if you need to use some other flavor -- when it doesn't act like you think it will. further, because of the markdown flavors doing different things, and differently, the underlying "mental model" has grown to be badly fragmented, so any reliance on "what seems intuitive" is no longer a dependable guide on what will happen. this shattering of the "intuitive" asset might prove -- in the long run -- to be the most serious problem of all of them. moreover, despite continuous calls for a "standardization" of markdown, the various developers all have a stake in their own personal vision and product, therefore, none wants to "standardize" his flavor out of its very existence by making it "redundant" with another one. their recalcitrance has become so firm that they don't even bother to debate new proposals in dialog or discussion; they simply fail to respond in any way. which is probably good, in that it saves everyone lots of wasted time and hope; but it won't, you know, yield a solution. so we have these problems being caused by this plethora of developers iterating -- separately -- around a shallow core, fragmenting a pathetic entity too weak to stand by itself independent of them, and now they are resisting any solution to this big jigsaw puzzle because each one is holding tightly to his own little piece, reluctant to sacrifice it to another player. and thus the problems are now intractable. it's worth noting that gruber has thus far stared down all attempts to fix this shit. perhaps recognizing the futility of _any_ chance of consensus, he will not even try. he just continues to insist _he_ is happy. meaning there is nothing on the horizon. no white knight; nix on prince charming. so, as the uptake for markdown increases, a ton of users will get bit in their butts. and the more that come in, the more that will experience a need to cross flavors, and find themselves bitten in their butts. so even as the positive affect climbs up, as more and more people stumble upon the appeal of light-markup and come to love it, so too will the negative affect tag along, correlated strongly; and that, my friends, is the state we label "severe ambivalence." probably not the zone you want to be in. but markdown has been tied to the tracks, and the only thing coming now is a train. it is inevitable. the only way that you can _not_ _see_ _it_ is to close your eyes. it's a good thing world peace does not hang in the balance. "just documents." *** now that we've done "ugly" and "bad", we can move on to "the good". hooray! this is where all the people who came for a rant can leave now. see ya later! the good so let's focus on the positive for a bit. markdown is now showing up _everywhere._ and the signs are that it'll keep growing, possibly even faster than its current rate. the cause of light-markup is well-served! so let's point our telescope at three stars shining most brightly up in markdown's sky. *** john macfarlane "pandoc" -- http://johnmacfarlane.net/pandoc -- is a tool that converts between a bunch of text-file-formats and systems, _including_ markdown, so it can be extremely useful, and is one of the few brighter spots in this mix. one part of the f.a.q. on the "pandoc" site documents the many inconsistencies between _some_ of the many various markdown variants -- but not all, as new implementations are cropping up regularly, with new wrinkles -- while another section over there considers: "what are some big questions that markdown's specification does not answer?" thus, if you were wondering whether i maybe "exaggerated" all the glitches, as a stunt for the lurkers, you should check out the full array of stuff. (and you will realize that i _chose_ to _not_ throw meat to all those rambunctious coyotes, or i would have pointed to this page up above, and detailed it all in an excruciating manner.) > http://johnmacfarlane.net/babelmark2/faq.html the f.a.q. section also has a web-app which lets you input real-life markdown fragments to each of the various flavors to learn what each one actually delivers for that fragment. so much handier than installing all of them. again, if it's important in any way for you to know the state of uncertainties in the markdown arena these days, you absolutely must definitely delve into details there, so you'll grasp the scope of the nightmare. or if you're _experiencing_ glitches in a markdown file, this is a great resource to help you debug the crappiness. and if you come up with something new, file a report. john macfarlane is the berkeley professor who makes the _free_ _and_ _open_ "pandoc", meaning he has donated a boatload of time to the cause, and that deserves recognition. so if you need conversions for other formats for markdown to be viable in your workflow, pandoc is the _first_ tool you should review. "pandoc" has proven itself, over and over, as being a tool that is extremely valuable. fletcher penney likewise with "multimarkdown composer" as a tool that's proven it is very valuable. > http://multimarkdown.com "composer" is a text-editor purpose-built for "multimarkdown", by fletcher penney; he is the creator of "multimarkdown", so integration of the two is nice and tight. "multimarkdown" is the markdown variant which is the most powerful of all of 'em, so it was already the leader of that pack, even before fletcher programmed "composer". "composer" is a mac text-editor app that funnels its text through "multimarkdown" to create output, primarily in .html form (the typical output of markdown flavors), but now also as .rtf, and .pdf, and .epub. "multimarkdown" format is _free,_ but -- to justify all the time spent coding it -- "composer" is a $12 commercial mac product, readily available over at the mac app-store. because "composer" is geared specifically toward "multimarkdown", it makes it easy to write and edit your text in that format. for instance, let's say that you are making an ordered list, and you have just finished typing an item there. when you hit _enter,_ "composer" automatically inserts the coding to indicate the start of the next list item, so you can just start typing away at that. hit _enter_ at the end of that, and you're ready for the next item. at the end, press _enter_ twice in a row, and the app knows that the empty item signals that you're done with the list, so it deletes that empty item. it sounds like a little thing, and, by itself, it is. but when it gets combined with many such little helpers, it all adds up, and you will find you get used to them quite quickly. as "multimarkdown" is the best variant -- with more power than other flavors -- and holds a slight edge over the others, i once thought that his "composer" would allow fletcher to break clean from the pack of markdown flavors and take a huge lead (since none of those other flavors had the benefit of an editor specialized for them), thus resolving the inconsistency log-jam, by virtue of "multimarkdown" becoming the "de facto default" markdown flavor standard. but fletcher's initial updates came slowly; "multimarkdown" is still leading the pack of all the markdown flavors, but it hasn't broken out to the point that they all quit. and part of the reason is that the other markdown flavors soon received one of the most significant advantages "composer" briefly had to itself -- a live preview. and for that development, behold the third star in our markdown firmament. *** brett terpstra the best thing for markdown at this time -- no doubt about it -- is brett terpstra, who created the markdown-live-preview app for mac desktops that is called "marked". > http://marked2app.com "marked" is also a $12 commercial mac app. it lets you use your favorite text-editor -- any app that saves a plain-text file -- to write your markdown-formatted text-file, and then "marked" will monitor that file being _saved_; when it discerns a new save, "marked" converts the file, in real time, to show you the resultant .html, _live,_ side-by-side next to your text-editor app. this instant preview -- _while_ you are actively editing -- is quite informative, and the fact that you can pair "marked" with _any_ text-editor makes it special. "marked" does nothing that will give your text-editor app any special "markdown mojo" (you'll have to apply things "manually"), so it's not quite as good as "composer", but a live-preview is worth $12 by itself. (especially when you're editing "by hand".) i have long held that the side-by-side interface is a vitally-important factor, when using a light-markup system, since it creates a distinct mental separation between the _input_ (plain-ascii text) and the _output_ (nicely-formatted rendering). input in one window, output in the other. it keeps everything straight in your head. this gets at one of the crucial topics in discussing text-editing these days, especially pertaining to the web and a struggle to ditch ms-word, to make text "semantic", not "presentational". since most of our users grew up using word-processors, their modus operandi is to "make it look good", which doesn't translate so well to our new web world, where output displays aren't as fixed as ink put on an 8.5x11-inch sheet of paper. to emulate the w.y.s.i.w.y.g. approach which our users have fondly embraced, in a decades-long love-affair with the wonderful miracle of word-processors, some coders have strived to develop a "hybrid" light-markup interface which will _combine_ the input and the output -- smooshes both into a single window -- but i firmly believe that will only cause confusion for the users. (not to mention for the designers of such an interface.) in my strong and longly-held opinion, a "combination model" is the _worst_ possible approach we could be taking, precisely since it confuses the issue. no, we should do exactly the opposite! we need users to understand that input and output are fully separate, and also that the only way they'll get the output they want is to make edits to the input. this embraces the strong user desire to "make it look right", while constraining their edits to ones accurately reflecting the text's underlying structural integrity. in other words, if the _only_ way you can "make it look right" (on the "output" side) is to tag it correctly, i.e., structurally, (on the "input" side), you'll tag it right! the secret answer to that hard question of "how do we get people to stop making it look right?" is "stop trying to make them, and take advantage of their inclination". but the only way to invoke that mentality is for us to use a side-by-side interface, so the input and output remain separate; not just on the screen, but in your mind! the distinction is especially crucial when you are _learning_ markdown, but it's also still valuable when you are _writing_ it, since using the live preview window while you are working gives immediate feedback whenever you have tagged something wrong. and i firmly believe that if you experiment with a 2-up live-preview method of working, you will rapidly come to see what i mean. so i cannot recommend "marked" enough -- especially if you're _learning_ markdown! plus brett just came out with version 2, which offers a brand-new slew of tools (e.g., one to highlight word-repetition) that'll be of good utility to most writers: > http://marked2app.com nor is "marked" the first trip to the rodeo for brett, either; he is an old hand there. brett has also scripted several mac-os "services" for lots of markdown tasks. matter of fact, go see all his "projects": > http://brettterpstra.com/projects but of special interest to markdown, see the section for "markdown-service-tools". and, in particular, see this one; brett has a web-app, over at http://markdownrules.com, which offers converters that will translate both directions between markdown and .html. so say there is a web-page and you'd like to have its text in markdown format? easy! just put the u.r.l. into brett's converter: > http://markdownrules.com brett also scripted a "bulls-eye" plug-in, where you can select text from a web-page and then have that converted into markdown. and brett's projects go on and on and on. so heck yeah, go see everything from brett. odds are you will find more than one thing that helps you in your particular workflow. *** so, in this "good" section for markdown, i've featured the work of three individuals, all talented, all working very hard, and all contributing great stuff to the community of markdown users. big thanks to all three! there are, of course, _many_ people who have made contributions, in the past and continuing into the current-day, but these three individuals went far beyond the call. after the next section, on the future, i'll talk about some other markdown-related apps that you should be familiar with today, and highlight a couple other things to consider. but for now, let's look ahead a little bit. *** markdown's future so, next, we look to markdown's future. as more and more people start using markdown in more places to accomplish more things, they're bound to experience the problems that i've discussed here, and they will then realize these infrastructural shortcomings. so -- right along with inevitable growth -- markdown will have an equally-inevitable concurrent dissatisfaction that also grows. which will be kind of crappy for markdown. yet still, at the same time, markdown will continue to do the tasks perfectly well on most of those things people use it for now, such as blog pieces, comments, and the like. when your text has under 11 paragraphs, and doesn't really need much formatting, like a github read-me, markdown is fine. and even if you're doing a long document, with loads of styling, markdown will work well enough for a clear majority of needs. as living proof of this, many apps now do their manuals in markdown, and handling of these not-all-that-simple documents is done quickly and easily, without problems. it's not true of gruber-classic-markdown, but most of the extended flavors can now give whatever you need for many documents. multimarkdown in particular is full-serve. and you will not experience many problems _provided_ you stay with the same flavor. but you have to stay with the same flavor. it's only when you think you can painlessly switch from one flavor to some other flavor that you might well be in for a big surprise. so ensure, before you start your document, that the flavor you're using can handle it. because you don't want to have to switch. but even a switch won't be insurmountable. if you do find you have to change flavors, a quality-control pass on the new output should be enough to see incompatibilities, as long as it's a sharp-eyed close review. (very sharp-eyed. very close. important.) but you _should_ be doing quality-control often anyway, as a best-practice workflow. in other words, as long as you are properly sensitized to a real possibility of glitches, they might cost you some time and energy, yes, but it's unlikely they'll bite you in the butt. it is only if you do not have the wisdom or experience that glitches hide in markdown that you'll be surprised _when_ they bite. (there's no _if_ about it; they _will_ bite.) still, their bite is probably no worse than the "considered harmful" bark i've just made, in my title here, so don't worry, you'll live. *** a few more things so let's talk about a few more things. first of all, as you can probably tell, no, sincerely, i do not hate markdown. to the contrary, in _many_ ways, i'm a long-time fan of markdown. and i'll make sure you know that. light-markup systems heck, i loved markdown before it _existed._ because markdown is what's known as "light-markup". which, if you consult wikipedia, gets called "lightweight-markup". > http://en.wikipedia.org/wiki/lightweight_markup_language but i don't think it's "lightweight" at all; i believe it's a heavy hitter. i _love_ _love_ _love_ light-markup! i've loved it for well over a decade! so, to repeat, i'm a long-time fan of markdown specifically and also all other types of "light-markup", going back to "restructured-text", which was one of the original ones. (ok, actually "structured-text" was probably _the_ original, but it got re-mixed into "restructured-text".) restructured-text "restructured-text" is well-known, since the python community has been using it for a long time as its primary format for documentation. > http://docutils.sourceforge.net/rst.html as that implies, restructured-text has proven itself up to the task of doing technically-oriented material for a technically-oriented audience. so much for the "lightweight" slur. ascii-doc "ascii-doc" is another format which has enjoyed a wide implementation, even though it is not so well-known. it is also one of the "heaviest" forms of light-markup, so it's not a surprise that it mainly gets its most attention from a plethora of larger organizations. > http://www.methods.co.nz/asciidoc ascii-doc can generate output in a variety of formats, proving itself in a impressive range of situations, even more so than restructured-text. for instance, ascii-doc was adopted by many in the o'reilly camp nowadays, and is now used as the primary engine for their newest system, called "atlas", which they steer their authors toward. "atlas" also takes markdown as input, but it makes clear that markdown is not really fully up to snuff for the job. (it must've really killed some people over at o'reilly to eat crow and admit that i was right all along when i was lecturing them to favor light-markup, laughing at their docbook bloatware, and heaping scorn upon their blatant x.m.l. promotion at their conventions for the publishing industry, ones which they no longer even bother to conduct, probably because they're embarrassed to concede that all of their advice was wrong, wrong, wrong, wrong, wrong.) textile among other tech kids, "textile" was often one of their first exposures to any form of light-markup, and thus it initially enjoyed good prominence, especially when it was fairly newish. while not disappearing entirely, by any stretch of the imagination, it has nonetheless faded in importance, as evidenced by the fact that the best link i can give for it is wikipedia. > http://en.wikipedia.org/wiki/Textile_(markup_language) in the early days, restructured-text, ascii-doc, and textile were the top 3. despite the numerous other players -- which could also include all of the wiki-markup-oriented derivations -- in the light-markup game, those 3 were the leading contenders at the very top of the light-markup heap. markdown's arrival but then markdown rode into town. markdown came from john gruber, who was ascending on the wave of blogging's big rise, and it benefited from the exposure which he gave it. and thus markdown's adoption continued to grow along with gruber's audience. true, for a while, that adoption was limited to relatively "minor" places, like the comment sections of blogs. but in the last few years, markdown has leveraged critical mass for itself. it is used at http://stackoverflow.com and http://github.com; considering that these sites have a massive following among techies on the cutting-edge, it was easy to predict a blossoming. as these techies were exposed to the ease and convenience of light-markup, they were converted to its usefulness. so, sure enough, now markdown is appearing in all kinds of tech places, including ones of some significance. among these new appearances was a recent emergence of "static blogs". tech-minded people found it simple to create a mass of plain-text-files, and then use a markdown script to convert them to the .html-files that can then constitute their static blog. this movement away from mysql to a flat-file approach is one that might ramify deeply in the future. and techies have been increasingly using markdown to make manuals and documentation for their apps. even these people, for whom .html comes "naturally", seem to want to use a light-markup format instead, both to avoid the tedium of markup and to be able to edit "clean" text. the fact that the techies now prefer predominately to use light-markup is quite an important demarcation. *** markdown in public and it wasn't just techies focused on handling of their own content, either. developers soon realized that it was a benefit for "unsophisticated users" to let them write in markdown, so as to spare 'em from the pain of .html. (and to ensure their input was clean!) i.o.s. apps the most stark place for new uses happens to be the ipad and iphone. literally dozens of i.o.s. apps use markdown these days, thanks to its high profile among developers. this is especially true because many of the apps on those machines are geared towards jotting down notes, not what's typically called "writing". so i won't focus much on those apps, as that's an essay of its own, but also because i'm much more interested in the use of light-markup for "writing", so, for that, we will turn to the web. if you're curious about i.o.s. apps, brett terpstra made a review page: > http://brettterpstra.com/ios-text-editors for the record, brett's summary table has entries on 99 different i.o.s. apps! you can also search the app-store for "markdown" for a sense of the breadth. of course, lots of the i.o.s. apps are hooked up with the web as well, so a person can work on a file _either_ with a mobile device or on the web. but it sharpens our attention to look at web-sites that focus on _writing._ draftin dot com a number of new sites have writing -- and re-writing, version-tracking, editing, collaborative writing, etc. -- as their primary reason for being, and incorporate markdown as well. one of the best examples is "draft": > http://draftin.com "draft" is a site that has gotten lots of praise, from a wide swath of people, and has a very healthy base of users, some of them paying the reasonable price of $3-per-month for the service, which hyped easy version-tracking as its primary benefit when it started out, but has since offered a number of other services that are of value to the writer. editorially markdown is also used at "editorially", a site coming out of a very long beta, targeted on the collaboration process occurring between writers and editors. > http://editorially.com ghost and again, returning to blogs for a bit, one of the most high-profile initiatives in the blogging world today -- "ghost" -- made big noise about using markdown, as one of its marketing messages in a kickstarter campaign that made its goal within a few days, and then went on to raise some $300,000+ by its conclusion. > http://ghost.org "ghost" has recently begun to be released, and it will be of particular interest to me, since it has made the 2-up input/output user-interface a major jewel in its crown, so many people will be encountering it for the first time in constant heavy use, and i'm curious as to how they'll react. wordpress and i should mention that "wordpress" just this week announced that it is now supporting markdown in its editor. whether or not this is in response to the "ghost" initiative is not clear; it may, or perhaps it's a coincidence. dillinger but even long before "ghost", markdown was being adopted by web-apps which employ a methodology of cloud-storage, where you control where files are saved. one of my favorites there is "dillinger", which also has the 2-up user-interface. > http://dillinger.io "dillinger" can save your files to "dropbox", "google-drive", or "github" -- your choice. like i said, "dillinger" is one of my favorites, of these online editors, but there are _lots_ of them, all basically pretty much the same, so look around until you find your favorite. a recap of them all would be another essay. simplenote but i'll mention one another important one, however, namely "simplenote", because it was an early cloud-based note-taking app that used plain-text as its primary format, and it built an excellent _sync_ capability which other similar apps could use as well. > http://app.simplenote.com "simplenote" sync was known for its speed and for the high quality of its performance. these are both hard problems, which giants (like apple) have stumbled on (often badly), so it was great for a small guy to get it right. "dropbox" is the gold-standard in this regard, but many developers claim "simplenote" sync is even faster and more accurate, high praise. (although, in fairness, "simplenote" only does plain-text files, while "dropbox" does all types.) "simplenote" made it very easy for developers to use their service, in the early days, thereby earning the admiration of many early-adopters. "automattic", makers of "wordpress", recently purchased "simplenote" -- mainly because of "simperium", its sync -- so it's big-time now. and with editors for i.o.s., the mac, android, and the web, "simplenote" is a shining pointer toward a new reality where all our documents are available to all our machines all the time. (and perhaps this is why "wordpress" itself is now supporting markdown in its own editor.) *** long-form light-markup now let's swing back to long-form stuff again, because long-form is my specialized interest. you might wonder what i mean by "long-form". it should be obvious that "long-form" refers to a text that is longer rather than shorter, but other considerations also come to bear. _books,_ of course, are the prototype of the long-form document, but i define long-form more broadly as "any document that contains easily-differentiated sections and thus benefits by offering a table of contents to the reader". in a book, those sections are "chapters", plus the front-matter and back-matter parts; but under this definition, a scientific article would qualify as well, with sections like "title page", "abstract", "introduction", "method", "results", "discussion", "references", and "appendices". likewise with an annual report, a legal brief, a manual for a gadget or car or appliance, or (as i've mentioned) software documentation. in this respect, a long-form document will often resemble a full _web-site_ -- with each section living on its own web-page -- and not merely one individual _web-page,_ which is the product typically pictured as the output from markdown. leanpub web-sites that help writers create long-form are just starting to pop up, in what appears might be a big trend, but there's one that has been around for a couple years already, and deserves mention. it's called "leanpub", and it can be found here: > http://leanpub.com more than just an authoring-tool, leanpub also offers services as a bookstore, and is touting a "release-early-release-often" publishing model, where it makes a book available to purchasers while it is in the process of being written so that the book can (hypothetically) be strengthened by the feedback provided by the early purchasers. as a publisher/bookstore/whatever, leanpub gives very good "royalties" -- in the range of 90% -- and gives its authors/publishers/whatever an ability to offer _variable_ _pricing_ on a book, a flexible touch. (it also lets authors donate royalties to a charity.) while i sincerely doubt that a "release-often" model is the best one in today's world, where people are too busy to read a book once, let alone many times just to see what's been changed between versions, i certainly think that it's an experiment worth trying, and i'm glad somebody has the balls to do just that. there are other things i don't like about leanpub -- like the workflow which forces its users to chop up their books into a separate file for every chapter, which i have found increases consistency errors -- but as they say, "that's what makes a horse-race". and i do commend "leanpub" for creating a platform that concentrates on the long-form book experience. *** scrivener while we're on the topic of books, let's swing back, for just a minute, to the world of offline programs, because a big one in regard to books is scrivener. scrivener is far more than a markdown text-editor; it's a smorgasbord of capabilities for writing books (cork-storyboarding, an outlining tool, and so on). it's probably over-the-top bloated functionality for most markdown users, who generally tend to favor the "distraction-free" side of the "busy" continuum, but it would be a clear omission not to mention it, since scrivener is one of the few book-focused apps. as such, it offers .epub output, not just typical .html. > http://www.literatureandlatte.com further, it's a very revealing fact that many users who _do_ love "scrivener" love it _very_ _strongly._ so if you think you'd like a book "project manager" -- which is how the "scrivener" hype describes it -- for your writing endeavors, check out "scrivener". any program that earns this much loyalty is special. texts.app and as we are talking offline, if only for a brief time, i can mention another few apps that are stand-out, in that they have a considerable book perspective. one is called "texts". first of all, it is cross-platform, with programs for both mac and p.c., and i.o.s. too. further, it outputs .pdf, ms-word.doc, and even tex, in addition to the expected .html and .epub e-books; so that represents a rather complete package of rad. and, for a limited time anyway, it costs less than $15. "texts" is one of the apps that attempts to combine "input" and "output" in the same window, so if you think you would be attracted to that method, try it. > http://www.textseditor.com textastic the other is called "textastic". there's no p.c. version, but there are versions for iphone, ipad, and the mac. this is a programmer's editor, with syntax-coloring -- yes, the colors are applied to markdown syntax -- but it's handy as it syncs to either dropbox or icloud. > http://www.textasticapp.com one more section here, and then we're all done. *** zen markup language i, too, have developed a system for long-form texts, one that's firmly grounded in a light-markup format that's called "zen markup language", z.m.l. for short. z.m.l. was derived from e-texts at project gutenberg -- i have been working on it for over 15 years now -- so it springs from the structures found in actual books, which differs philosophically from markdown's source (i.e., things that are possible in .html on a web-page). additionally, z.m.l. considers a wide range of output (such as .epub, .mobi, and .pdf), over and above the single target focus on .html destined for a web-page. perhaps most significantly, from the standpoint of this "considered harmful" essay, however, is the fact that with z.m.l., i intend to sidestep some of the problems inherent in markdown, or which have emerged with it. long-form, sections, purpose of each section, etc. ?? summary in conclusion, let's review the problems with markdown. 1. gruber's classic version is far too primitive. 2. gruber's classic version isn't detailed enough. 3. gruber's classic version exhibits edge-cases. 4. gruber continually refuses to acknowledge this. 5. the extensions added capabilities haphazardly. 6. the extensions often conflict with each other. 7. the extensions destroy the "intuitive" asset. 8. the extension developers refuse to collaborate. 9. markdown infrastructure isn't cross-plat enough. 10. markdown infrastructure is far too piecemeal. 11. there is absolutely no way out of this quagmire.
it appears that you have javascript turned off.