@@ 13,6 13,10 @@ Installation:
 
 API Documentation: http://godoc.org/bitbucket.org/telesto/hackurist
 
+See
+[bitbucket.org/telesto/hackurist/cmd/hackurist/main.go] (https://bitbucket.org/telesto/hackurist/src/0d46764b30bb877b86d45959dc0be5e1771d164e/cmd/hackurist/main.go?at=default)
+as an example on how to use this library.
+
 
 command line tool
 -----------------

          
@@ 31,7 35,13 @@ or download the binary:
 Usage: See
 
 	hackurist -h
+	
+Some examples:
 
+	hackurist help
+	./hackurist -a :5001 region-pops list
+	hackurist -d lua "print(df.global.world.units.all[0].name.first_name)"
+	
 Feedback/Contact
 ----------------
 There is an [anouncement topic](http://www.bay12forums.com/smf/index.php?board=29.0) at the official dwarf fortress forums. you can contact me by sending a pm.

          

@@ 47,7 47,7 @@ func run(address, cmd string, args []str
 		return err
 	}
 	result, err := conn.RunCommand(cmd, args)
-	fmt.Print(string(result))
+	os.Stdout.Write(result)
 	if err != nil {
 		return err
 	}

          

@@ 64,6 64,9 @@ func (c Conn) Close() error {
 	return err
 }
 
+// These are representations of the dfhack RPCHandshakeHeader, defined in RemoteClient.h.
+// As these values don't change they are kept as raw byte sequence
+// (see header documentation for more information).
 var (
 	handshakeRequest  = "DFHack?\n\x01\x00\x00\x00"
 	handshakeResponse = "DFHack!\n\x01\x00\x00\x00"

          
@@ 97,8 100,13 @@ func (c Conn) ShakeHands() error {
 
 const sizeHeader = 8
 
-// marshaled: xx00yyyy, where x=id and y=size
-// size is ignored when id = RequestQuit
+// header is the equivalent of the dfhack RPCMessageHeader, defined in RemoteClient.h.
+// dfhack writes the header in front of every message.
+// The header is written raw to the connection, so we need to simulate this.
+//
+// The serialized header looks like this: "xx00yyyy", where "xx" is the header id and y the
+// size of the attached message. 0 are struct padding bytes, these are ignored.
+// The numbers are little endian.
 type header struct {
 	id   headerId
 	size int32

          
@@ 134,8 142,7 @@ func (c Conn) readHeader() (*header, err
 }
 
 // RunCommand sends a rpc command to the server.
-// It reads the response, processes it and returns the output
-// ready for a text client.
+// It reads the response, unmarshals it and returns the output.
 func (c Conn) RunCommand(cmd string, args []string) ([]byte, error) {
 	protoCmd, err := proto.Marshal(&dfproto.CoreRunCommandRequest{Command: &cmd, Arguments: args})
 	if err != nil {