# HG changeset patch
# User telesto
# Date 1418728790 -3600
#      Tue Dec 16 12:19:50 2014 +0100
# Node ID 71e5c26f841a15c40a0a066ba45bae8e7f0e186f
# Parent  1d4e120dedb80c5a82ef7bd3cb6ce49a1c8d47e0
fixed the mess left behind by wrong tagging

diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -13,6 +13,10 @@
 
 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 @@
 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.
diff --git a/cmd/hackurist/main.go b/cmd/hackurist/main.go
--- a/cmd/hackurist/main.go
+++ b/cmd/hackurist/main.go
@@ -47,7 +47,7 @@
 		return err
 	}
 	result, err := conn.RunCommand(cmd, args)
-	fmt.Print(string(result))
+	os.Stdout.Write(result)
 	if err != nil {
 		return err
 	}
diff --git a/hackurist.go b/hackurist.go
--- a/hackurist.go
+++ b/hackurist.go
@@ -64,6 +64,9 @@
 	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 @@
 
 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 @@
 }
 
 // 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 {