Documentation for Fun and Profit with AsciiDoc!

(editor's note: neither fun nor profit guaranteed)

For the last week, I've been writing documentation of various things in preparation for leaving my current job. We have one app in particular that had fairly sparse end-user documentation, and it's safe to say that I'm the only perlaphile in the office, so I started using vim to write a README file for it.

One thing let to another, and vim started syntax highlighting the file on me, so I pulled up a quick :se syntax to see what the heck was going on.

Lo and behold, I found out that vim uses AsciiDoc for its README (and .txt) syntax highlighting. This little gem makes writing documentation in plaintext pretty easy, and before I knew it, I was knee deep in constructing a man page for the scripts that I was documenting.

The basics of AsciiDoc's man syntax are simple and straightforward:

= A_PROGRAM(1) =

NAME
----
a_program - This program does something cool.

SYNOPSIS
--------
a_program [--frob]

USAGE
-----
--frob::
  twiddles the frobs (disable frob-twiddling with --no-frob)

BUGS
----
Does not actually twiddle frobs.

SEE ALSO
--------
a_program.conf(5)

...and so on. The top line is the document title, and has to include a section number to be valid for man. Then, every section (NAME and SYNOPSIS are required, and must be first) is underlined. The :: syntax is for a definition list, which works great for documenting argument lists. It's so easy and neat to be able to write man pages in something easier than perldoc that I actually was accused of enjoying writing documentation.

The real gem today came in the form of a Makefile, though:

all: a_program.1 a_program.html

%.1: %.txt
	asciidoc -b manpage -d docbook -o - %< | docbook2man -

%.html: %.txt
	asciidoc -b manpage -d html -o %@ %<

Now, with just make, I can generate both the man pages, and HTML documentation for people who are into that sort of thing.

:wq

You Cannot Get Ye Telnet

Debugging a mail setup at work (on Windows :(), I tried unsuccessfully to find a program to just open up a TCP connection to a random host and port. But, we do have git installed, which means a full copy of bash. And that means that /dev/tcp and /dev/udp are available, despite /dev not existing.

So, I wrote telnet in bash (extra lines added by... chrome?blogger):

#!/bin/bash

HOST=$1
PORT=${2-23}

exec 3<>"/dev/tcp/$HOST/$PORT" || exit 1

while read line ; do
        echo $line
done >&3 &

while read line ; do
        echo -en "$line\r\n" >&3
done

It's not a perfect drop-in replacement, but now I can at least test email:

$ ./telnet.bash alt1.aspmx.l.google.com 25
220 mx.google.com ESMTP c64si6457617yhj.60
HELO localhost.localdomain
250 mx.google.com at your service
MAIL From:<aaron@xxxxx>
250 2.1.0 OK c64si6457617yhj.60
RCPT To:<aaron@xxxxx>
250 2.1.5 OK c64si6457617yhj.60
DATA
354 Go ahead c64si6457617yhj.60
Subject: test
Date: Mon, 08 Aug 2011 16:16:29 -0700
From: "Aaron Fellin" <aaron@xxxxx>
To: "Aaron Fellin" <aaron@xxxxx>

This is a test email.

I <3 bash
.
250 2.0.0 OK 1312845535 c64si6457617yhj.60
QUIT
221 2.0.0 closing connection c64si6457617yhj.60
^D

:wq