Writing documentation on OS X
Just some notes I've made while creating documentation for
Abacus.
I'm developing the documentation primarily on OS X using MultiMarkdown,
targeting Qt Assistant style HTML as well as web-hosted HTML.
Tools
- Emacs. The native Cocoa build
looks much better on HiDPI displays than the X11 build I was using before.
Combined with this tiny shell script to edit files from
the commandline it's at least as usable as TextMate or Chocolat for non-code
editing.
- Inconsolata -
it's a nice monospace font that doesn't make my eyes bleed.
- Markdown mode
for Emacs. I'm actually using MultiMarkdown, which is a superset of Markdown,
but markdown-mode is working better for me than the only multimarkdown-mode
I could find.
- More emacs plugins and configuration - mic-paren, yasnippet,
fill-column-indicator all set up in my .emacs
- Marked - a little OS X app that
monitors a markdown format file and previews it each time you save it. Nothing
you can't do with a few scripts, but Marked does it very well and very
simply. Well worth the four bucks.
- Skitch for taking and annotating
screenshots. It has some annoyances, not least the lack of scriptability.
I have my main images folder symlinked to my desktop, so I can drag images
from skitch directly to it. I'm saving .skitch format as well as .png so I
can go back and reannotate existing shots or move annotations onto updated
shots.
- Autodoc combined with a
slightly
hacked up template to generate markdown format documentation of the PostgreSQL
schema.
- Pod::Markdown to
import some perl documentation.
- And some perl to glue it all together.
Characters
There are lots of characters that it's useful to have in documentation
that can't easily be typed. If you go to System Preferences →
Language & Text → Input Sources then you can enable Unicode Hex
Input - which lets you type in unicode by holding down the option key
and typing the hex code.
- ⌘ 2318 - the Command Key symbol
- ⌥ 2325 - the Option Key symbol
- ⇧ 21E7 - the Shift Key symbol
- ⇥ 21E5 - the Tab Key symbol
- ⏎ 23CE - the Return Key symbol
- ⌫ 232B - the Delete Key symbol
- → 2192 - right arrow, useful for menus
(If you can find the character you want in the Character Viewer, you can
right click on it to copy information about it, including the unicode code
point, to the clipboard).
