Find file
Fetching contributors…
Cannot retrieve contributors at this time
95 lines (65 sloc) 4.43 KB

Setting up your editing environment

This doc describes how to set up an environment on a Mac to write for Maker Press. (Or, I should say, it’s my running notes for it.) Depending on your system, you might have a bit of work to do to get things up and going. So, take this document with a grain of salt.

We’ll need to do a few things to get going:

  • Install MacPorts to make it easy to get new packages

  • Install git and asciidoc, which is a package for formatting text

  • Install TextMate, as well as a few bundles

The following sections explain this in more detail.


You will need the XCode development tools and X11 (which comes on some Macs). Next, you’ll need MacPorts, which makes it much easier to install everything you’ll need. You can find it at the MacPorts website, which has all the instructions you need to install it for your system.

One annoyance I had on MacPorts is that it lists the OS versions by name, rather than number, which I found annoying.  You can find your OS version by clicking the Apple at the top left corner and then selecting "About this Mac" and then find the corresponding name using the list below (from Wikipedia):

* Version 10.0: "Cheetah"
* Version 10.1: "Puma"
* Version 10.2: "Jaguar"
* Version 10.3: "Panther"
* Version 10.4: "Tiger"
* Version 10.5: "Leopard"
* Version 10.6: "Snow Leopard"
* Version 10.7: "Lion"

Then make sure your PATH is correct in ~/.profile. So here are the two lines you’ll want (updating for your username):

export PATH


If you don’t already have git, you can use MacPorts to install it. Just drop into the terminal and type:

$ sudo port install git

It should fire up and install with no problems.

asciidoc, a2x (8.6.4)

Asciidoc refers to two different things: a wiki-like markup language you can write in, and the various tools that convert that markup into various other formats. This section describes how to set up the tools. You can probably already see the punchline coming, but here’s how you set up the asciidoc tools on your system:

$sudo port install asciidoc

The downside of this is that this step takes a very long time. So, be prepared to run it and then go out and get some coffee. Or, two coffees.


You can edit your documents in whatever editor you like — vi, emacs, or whatever. I’ve been using TextMate, an editor for the Mac that is popular in the developer community. It costs about $60 U.S., but it’s got some addictive features that make it worth the price. Plus, you can try it our for free for 30 days.

On of the coolest features of TextMate is that it offers a bundles — collections of macros, commands, snippets, drag commands, templates, preferences, and language grammars — that make development much quicker. There are two main bundles I’ve been using: asciidoc and git.

Install the asciidoc bundle

The AsciiDoc bundle makes it much easier to work with AsciiDoc in textmate by offering things like automatic previews, source highlighting, and so forth. Here’s what you do:

mkdir -p /Library/Application\ Support/TextMate/Bundles
cd ~/"Library/Application Support/TextMate/Bundles/"
git clone git:// "AsciiDoc.tmbundle"
osascript -e 'tell app "TextMate" to reload bundles'

Once the bundle is installed, you’re asciidoc markup will have be al the color coded goodness you’ve come to expect. One note: you have to give the files a ".asc" extension for the color coding to happen.

Install the git bundle

The git bundle allows you to save stuff in git right from within TextMate. Not sure what this buys me yet, but here are the commands:

mkdir -p /Library/Application\ Support/TextMate/Bundles
cd !$
git clone Git.tmbundle
osascript -e 'tell app "TextMate" to reload bundles'

You’ll need to add a path variable to tell TextMate where git is installed. First, locate git:

$which git

Then go to "Preferences → Advanced" and click the "Shell Variables" tab. Then add a variable named "TM_GIT" and put in the path to git you found on the last step.