Markdown and Writing

While major writing projects requiring lots of research, sometimes I just want to write up several paragraphs in an article without a lot of fussing about. Text editors are perfect for this, while also guaranteeing, unlike Word, Pages, or even more open formats, maximum future readablity and recoverability. Unfortunately, going back in to properly add links, italicize or quote text, etc., can be a pain.

Thus was born Markdown. Markdown is both a plain-text syntax for tagging text for web/formatted output and a program of the same name that converts text in the markdown syntax to valid HTML. Since the formatting and syntax use conventions already long common in emails, it’s very easy to mark up the text, and text formatted this way is highly readable even as plain text.

Since I don’t feel like breaking out a massive writing tool like Open/Libre Office or Scrivener every time I want to write up a few paragraphs, and since I absolutely hate going back after the fact to format everything in even the best WYSIWYG implementations when I could do it from the keyboard as I type, I really appreciate the ease of use.

I also appreciate the fact that it’s widely available. While blogger doesn’t directly support it, it’s fairly easily added to WordPress, and is available for Posterous and Squarespace.

So here’s my cheat sheet that I keep in Emacs when I need a reference. Most of it is paraphrased from the original, and further details or nuance are linked to on a section-by-section basis to Gruber’s original spec:

Markdown reference:

You’ll note the headers for each section link to the respective section in Gruber’s syntax page for more information on the available options and nuances.

Block Elements

A paragraph is simply one or more consecutive lines of text, separated
by one or more blank lines

This is a new paragraph.

To FORCE a
newline,
use two
spaces.

Headers

Two types.

This is H1 (with ===== underneath)
====================================

This is H1 (with ===== underneath)

This is H2 (With ------ underneath)
-------------------------------------

This is H2 (With —— underneath)

Alternately, you can use ‘#’

# One '#' for h1

One ‘#’ for h1

## Two '##''s for h2

Two ‘##”s for h2

Three '###' for h3, and so forth.

Three ‘###’ for h3, and so forth.

Blockquoting

Markdown uses email-style “>” characters for blockquoting. They can be
nested by adding additional levels of ‘>’. They can also contain other
markdown elements (headers, code blocks, etc…

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
>
>> Inset second level.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,

Inset second level.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse

Lists

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered Lists

Unordered lists use asterisks, pluses, and hyphens — interchangably — as list markers:

- Item a
- Item b
- Item c

Item a
Item b
Item c

Ordered Lists

Ordered lists use numbers followed by PERIODS. Order is irrelevant.

1. Dog
2. Cat
3. Kids

Dog
Cat
Kids

List items separated by a space have the content of the <li> wrapped
in a <p> paragraph tag.

Code Blocks

To produce a code block in Markdown, simply indent every line of the
block by at least 4 spaces or 1 tab. For example:

This is a code block.

A code block continues until it reaches a line that is not indented
(or the end of the article).

HTML in a code block is converted to entities, and Markdown syntax is
NOT processed within a code block.

Horizontal Rules

You can produce a horizontal rule tag (<hr />) by placing three or
more hyphens, asterisks, or underscores on a line by themselves. If
you wish, you may use spaces between the hyphens or asterisks.

---
***
___

Span Elements

Links

Inline or reference. In both styles, the link text is delimited by
[square brackets]. See the original
syntax for a
more thorough explanation of reference-style links.

This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.

Reference-style links

[This is linked] [id1] to something
[id1]: http://www.midknightgallery.com/  "Midknight Gallery home Page"

This is linked to something

Also, a reference can be implicitly identified by the linked content

  [The Midknight Gallery][] is a great site.
[The Midknight Gallery]: http://www.midknightgallery.com/ "Home"

The Midknight Gallery is a great site.

Emphasis

**Bold**

Bold

*Emphasis*

Emphasis

Emphasis can be used in the middle of a word:

Crap*tac*ular.

Craptacular.

Backslash to escape literal asterix’s like this: \*.

Span of Code

Wrap a span of code within a paragraph with backtick quotes (`)

To include a literal backtick character within a code span, you can
use multiple backticks as the opening and closing delimiters:

``There is a literal backtick (`) here.``

Images

Inline image syntax looks like this:

![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")

Reference-style image syntax looks like this:

![Alt text][id]

Followed by the same syntax as reference links:

[id]: url/to/image  "Optional title attribute"

Miscellaneous

Backslash Escapes

Markdown provides backslash escapes for the following characters:

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

Automatic Links

Simply surround the URL or email address with angle brackets.

<http://example.com/>

Markdown will turn this into:

<a href="http://example.com/">http://example.com/</a>

Gamer Origin Stories

I often listen to a gaming-oriented podcast called “The D6 Generation,” focusing on board and miniature games. Most episodes include an interview with a member of the game design community, and a question often asked at the beginning of the interview is to describe their gamer “Origin Story” – or how they became a gamer.

So how did I get into this hobby in the first place? For most gamers my age, it usually starts at Dungeons & Dragons, but actually, it started even earlier than that with regular straight-up wargames.

My first wargame I ever bought with my own money was a copy of Starship Troopers by Avalon Hill. I’m still not sure precisely where I first saw it – it may have been at the the Navy Exchange’s “toy” department. Perhaps it was the local hobby shop where I started looking for models more varied than the standard department-store airplane kits. It sure as heck wasn’t the standard Kmart, Sears, or JC Penny’s.

A long-time Heinlein fan even at the age of eleven, I was hooked. I started looking at other games. Fortunately for me (and unfortunately for any hope of sanity on the part of my parents), the husband of the couple that provided before-school care for us while my parents worked – the D.C. commute was a stone cold b*tch even then – was a wargamer and had a rather nice collection of AH games.. I lost a lot of time there playing Afrika Korps, Dune, and other games.

It wasn’t until we started staying over at a friends place after school in 5th or 6th grade that I first saw a copy of Dungeons & Dragons – a “box” set intended to get a foothold in toy and game stores – and promptly bought my own.

I started paying more attention to the weird books in “that” corner of the hobby shop. Sooner, rather than later, several friends and I had a fairly complete set of D&D books: the Player’s Handbook, the Dungeon Master’s Guide, the Monster Manual, and a number of modules. We also started looking at related stuff like Gamma World for post-apocalyptic Sci-Fi role playing, also by TSR.

Then I stumbled into a copy of The Traveller Book, a compilation of the first three manuals for the spacefaring RPG Traveller.

It was like finding home. I loved D&D – played it quite a bit through high school, but I’d spend hours going through the Traveller rules – especially the rather unique spaceship combat system (that used real newtonian mechanics!)

I’d also picked up a few more games – as I still played wargames. Panzerblitz and Magic Realm were added to my collection. I tried to convince my cousin to get into wargames by buying him a copy of Storm Over Arnhem based on the battle for Arnhem bridge that also inspired the movie “A Bridge Too Far.”

I also received my intro to Steve Jackson Games with the ludicrously fun “Car Wars,” spent a lot of money on Battletech right after it changed from Battledroids, and quite a bit of time in Shadowrun (magic and cyberpunk).

I then needed something with more flexibility, as the ever-changing editions to Traveller were driving me nuts, and I didn’t feel like keeping up. So I tried on GURPS (yeah, I know, I’m now a couple editions behind again, but that’s not bad for a game system I bought fifteen years ago…). While not very scalable and justifiably put down as fiddly, it had a unique character development system that allowed you to tailor your strengths and your weaknesses. It also had the flexibility needed to put out incredible resource books on everything from Vikings to Cthulhu and the far, far future. I ended up writing an article for the Pyramid (SJ’s in-house gaming magazine).

While dabbling in the vampire based games from White-Wolf games, I mostly skipped that as well as Magic: The Gathering, though I did end up getting quite a few cards for SJ’s loony “Illuminati: New World Order” card-based world domination game. The sheer lunacy of having Bjorne the viking dinosaur be the dictatorial ruler of California while running the world via TV advertisements was a sight to behold, and only a hint at the possible craziness in a game where all conspiracy theories could be true. Fasa actually had a very nifty game of armored grav tank combat that unfortunately petered out, but I dearly loved it.

These days, while I still have a few GURPS books, it’s mostly current boardgames, as I don’t have the time to invest in RPG’s. Descent, Survive! Warmachine, Mag Blast, Seven Wonders, etc. take up the majority of my monthly (sometimes bimonthly) playing time. I still have an old copy of Fortress Europa by Avalon Hill.

Emacs Fixes: Issue 2 – Transmit Compatibility

Transmit is an excellent FTP client, and hands down my favorite for the Mac. One of its niftier features is that of opening up a file on the remote server in a local editor, and uploading the changes automatically as they are saved in the editor.

This didn’t work out of the box in emacs, but I found a fix (h/t to Justillilly.com).

In your user directory, you’ll find a hidden file called “.emacs” Edit the file to add the following:

(setq backup-by-copying t)

Or, you can use the in-emacs preferences. If you type M-x (refer to the tutorial if you’re not sure what that means), and then “customize”, you’ll get to a customization screen. Select “Files”, then “Backup,” and toggle “Backup By Copying” on, and save the results. This will automatically add the entry to your ‘.emacs’ file.

Emacs Fixes: Issue 1 – Command Line Access

BBEdit and Textmate have a nifty tool they install so that when you’re in the command line, you can use a command like “mate” or “bbedit” to open a specified file. When the file opens in the editor, you can even close out the terminal window without crashing the graphical environment.

While it’s possible to open the GUI version of emacs from the command line with a specific file, it’s not quite so graceful if you forget and close out the terminal window – it crashes. I’ve tried several workarounds, but none of them are truly satisfactory, especially given that I don’t have to open up the terminal to see hidden files in the first place.

So of course you learn the basics well enough that opening up emacs in the terminal allows you to get done what you need, and then realize that to open a file anywhere on the drive, even hidden files and ones hidden from you by the computer, is drop dead simple.

C-x C-f (Control -X followed by a Control-f) allows you to open up the file browser, starting at your home directory (shown by a “~”). Hitting return then changes the display – the buffer – to the specified file or the contents of the selected directory. From there you can navigate through the file system with much of the same ease as you can through the terminal.

The lesson here is that you don’t even need the terminal to open up a hidden file. If you are in the terminal because you want to pipe the results of a command to emacs, you can either deal with the terminal – emacs is emacs – or bring up the graphical version. In the last case, just don’t close out the terminal window before closing out the graphical one.

In short – this isn’t an issue so much as it just works different.

Making Emacs Work the Way I Wanted it To.

Not all was sweetness and light. Changes mean things are different, and comfortable habits die hard.

Several things I missed from BBedit and/or TextMate, that were my priorities for “fixing” were:

Some things just are different. The graphical version doesn’t open from the command line without a few clunky integration issues, but it’s something that isn’t really needed either.
Out of the box, emacs didn’t save things back to disk so that Transmit, my FTP client of choice, would copy the changes up to the server.
Out of the box, the gui version of emacs doesn’t do color themes beyond the stock syntax-coloring-on-white.
Emacs didn’t do syntax hilighting for web pages using several programming languages (php, Javascript, and of course HTML are common), out of the box.
The syntaxt hilighting for multiple languages is still somewhat clunky due to a few bugs. Javascript is different from what I’m used to in BBedit, but just as good.
I am still learning how to implement “lint”-based debugging of javascript – a module that was available for TextMate.
I still need to learn how to program for emacs. I also haven’t learned to replace the convenient snippet structure that TextMate had, but the programming built into emacs is powerful enough to write entire games that run within emacs.
I still haven’t learned how to do a diff well – BBedit and TextWrangler (the free version with less features) still rule here.

First of all – keep in mind why I’m making this change. I’m finding myself in a position where I need a tool I can use anywhere. So, I’ll address how to tackle each of the first five that I’ve already solved, and any other issues that I fix to my satisfaction.

Getting Started on Emacs for Macs

Getting started on learning, really, really learning emacs is not, in and of itself, that hard, but will be markedly different from almost anything you’ve done in Word, Notepad, or any word processor you’ve used in the last ten years. Especially if you’ve started out on Macs in the first place.

You’ll have to unlearn a lot that you “know.” Also, if you’ve used other high-end text editors like BBedit, you’ll find some features not available right away out of the box.

As usual, the best way to learn is to actually do it.

A good site to learn more about about emacs as you get started is the Emacs Wiki. The site includes all sorts of information, including where to get different versions, and how to setup certain features. They also have an excellent page on where to get and set up Mac versions. I recommend you download the version compiled by Vincent Goulet because it includes several common packages and needed adjustments to work smoothly with the MacOS clipboard, and then that you skip on to do the tutorial.

The tutorial? Emacs is ‘self-documenting,’ and includes an excellent tutorial that leads you through the basic commands to move through a document and modify it. To start the tutorial, first start up emacs, and then type CNTRL-h (hold down the control key and press ‘h’, often referred to in emacs as C-h), followed by a ‘t’.

I’ll be back later to work around some things I missed from using BBedit and TextMate.

Necessity is a Mother

Simplicity is a balance. When it comes to tools, it’s often a balance between factors that cause drag like clutter and analysis paralysis, and the issue that a srewdriver makes a piss poor hammer. Too many tools for a job prevent you from mastering the ones you have and waste your time choosing between them. Not enough tools and you end up wasting time making do.

When discussing programming earlier, I discussed that you should choose a text editor, and stick with it, learn it. I also outlined why I chose the text editors I was using.

Well, circumstances have changed, and so have my tools.

One of my two go-to editors (TextMate) still has not seen any real progress. Any promises of an updated version fixing the problems I and others experienced still being so much vaporware. Also, I was spending most of my programming time in Xcode, and while Xcode has its faults as a text editor, losing the integration, code completion, etc. just wasn’t worth it. Lastly, I’ve found myself spending a lot more time in not only the Mac terminal, but working with other, linux computers, and needed to finally buckle down and learn an editor that would be available – or installable – almost anywhere I was logging in without having to learn yet another set of tools.

Thus I’m back to learning Emacs.

Why two tools? The friction of working around Xcode’s external editor support when it did exist – it’s not available in the latest update – was just too much trouble, and I still needed something I could use everywhere else. Screwdriver and a hammer.

So yes, there’s a learning curve. Emacs is insanely powerful and was designed in a pre-mouse world for handling text in a number of different contexts. But the basics are the same in the OSX terminal, Cocoa, a linux terminal, Windows, XEmacs under gnome or KDE. Whatever I learn, I learn once, and I can use it anywhere.

Acorn Update Available.

The guys at Flying Meat Software have released an update to their excellent, inexpensive image editor, Acorn, which is now up to version 3. One of the better reviews is here at Mac App Storm. Like many Mac apps these days, you can also get it via the Mac app store, allowing you to install it on all of your family computers.

While I personally won’t be switching to it from Pixelmator, what I’ve said before holds true – they’r both excellent programs and it’s more a matter of which suits your style. Check it out.

Note: Updated to dix a typo in mispelling “Mac”