Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
84 lines (56 sloc) 4.71 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 a package manager such as MacPorts or Homebrew to facilitate installing and managing additional software package

  • Install git, a distributed version-control system, 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, it is highly recommended that you install a package manager to automate further software installation. Whereas many Linux distributions have a default package manager (such as apt or yum), the Mac does not, but there are at least two reasonable package managers you can install. The first is MacPorts, and the second is Homebrew; read about each online to decide which better suits your tastes. (Don’t use Fink.) For the moment, we will stick with MacPorts.

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 punch line 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.

Enable command line usage

Later in this document I’ll describe how to start Textmate from the command line. To enable this, you must first configure your system so that it "knows" where Textmate is installed. The simplest way to do this is to use the "Terminal Usage" feature right in Textmate’s control bar. All you have to do is click "Help → Terminal Usage…​" and then click "Create Link". Enabling command line usage shows how this works.

textmate cmd line
Figure 1. Enabling command line usage