doc: Re-format the translator tutorial

Adjutst whitespace so that things don't overflow in PDF.

Change-Id: Ic75abccbe744aac327b1c6311afb4c13271a723d
Signed-off-by: Lubomir Rintel <lubo.rintel@gooddata.com>
Reviewed-on: http://review.gluster.org/5481
Reviewed-by: Vijay Bellur <vbellur@redhat.com>
Tested-by: Vijay Bellur <vbellur@redhat.com>

1 files changed, 141 insertions, 118 deletions

diff --git a/doc/hacker-guide/en-US/markdown/translator-development.md b/doc/hacker-guide/en-US/markdown/translator-development.md
index 6e367de54..77d1b606a 100644
--- a/doc/hacker-guide/en-US/markdown/translator-development.md
+++ b/doc/hacker-guide/en-US/markdown/translator-development.md
@@ -24,27 +24,27 @@ shared-object file, as follow (from `xlator.c`):
 
 ```
 if (!(xl->fops = dlsym (handle, "fops"))) {
-	gf_log ("xlator", GF_LOG_WARNING, "dlsym(fops) on %s",
-		dlerror ());
-	goto out;
+    gf_log ("xlator", GF_LOG_WARNING, "dlsym(fops) on %s",
+        dlerror ());
+    goto out;
 }
 
 if (!(xl->cbks = dlsym (handle, "cbks"))) {
-	gf_log ("xlator", GF_LOG_WARNING, "dlsym(cbks) on %s",
-		dlerror ());
-	goto out;
+    gf_log ("xlator", GF_LOG_WARNING, "dlsym(cbks) on %s",
+        dlerror ());
+    goto out;
 }
 
 if (!(xl->init = dlsym (handle, "init"))) {
-	gf_log ("xlator", GF_LOG_WARNING, "dlsym(init) on %s",
-		dlerror ());
-	goto out;
+    gf_log ("xlator", GF_LOG_WARNING, "dlsym(init) on %s",
+        dlerror ());
+    goto out;
 }
 
 if (!(xl->fini = dlsym (handle, "fini"))) {
-	gf_log ("xlator", GF_LOG_WARNING, "dlsym(fini) on %s",
-		dlerror ());
-	goto out;
+    gf_log ("xlator", GF_LOG_WARNING, "dlsym(fini) on %s",
+        dlerror ());
+    goto out;
 }
 ```
 
@@ -61,21 +61,21 @@ translator just for fun, so in this case you'd look in `rot-13.c` to see this:
 
 ```
 struct xlator_fops fops = {
-	.readv        = rot13_readv,
-	.writev       = rot13_writev
+    .readv          = rot13_readv,
+    .writev         = rot13_writev
 };
 
 struct xlator_cbks cbks = {
 };
 
 struct volume_options options[] = {
-{ .key  = {"encrypt-write"},
+{ .key    = {"encrypt-write"},
   .type = GF_OPTION_TYPE_BOOL
 },
-{ .key  = {"decrypt-read"},
+{ .key    = {"decrypt-read"},
   .type = GF_OPTION_TYPE_BOOL
 },
-{ .key  = {NULL} },
+{ .key    = {NULL} },
 };
 ```
 
@@ -123,10 +123,10 @@ then come back to `rot-13`.
   .type = GF_OPTION_TYPE_STR,
   .default_value = "",
   .description   = "Select between \"full\", \"diff\". The "
-		   "\"full\" algorithm copies the entire file from "
-		   "source to sink. The \"diff\" algorithm copies to "
-		   "sink only those blocks whose checksums don't match "
-		   "with those of source.",
+           "\"full\" algorithm copies the entire file from "
+           "source to sink. The \"diff\" algorithm copies to "
+           "sink only those blocks whose checksums don't match "
+           "with those of source.",
   .value = { "diff", "full", "" }
 },
 { .key  = {"data-self-heal-window-size"},
@@ -134,8 +134,8 @@ then come back to `rot-13`.
   .min  = 1,
   .max  = 1024,
   .default_value = "1",
-  .description = "Maximum number blocks per file for which self-heal "
-		 "process would be applied simultaneously."
+  .description = "Maximum number blocks per file for which "
+         "self-heal process would be applied simultaneously."
 },
 ```
 
@@ -152,11 +152,12 @@ priv->encrypt_write = 1;
 
 data = dict_get (this->options, "encrypt-write");
 if (data) {
-	if (gf_string2boolean (data->data, &priv->encrypt_write) == -1) {
-		gf_log (this->name, GF_LOG_ERROR,
-			"encrypt-write takes only boolean options");
-		return -1;
-	}
+    if (gf_string2boolean (data->data, &priv->encrypt_write
+        == -1) {
+        gf_log (this->name, GF_LOG_ERROR,
+            "encrypt-write takes only boolean options");
+        return -1;
+    }
 }
 ```
 
@@ -202,23 +203,23 @@ function that we just barely touched on last time.
 int32_t
 init (xlator_t *this)
 {
-        data_t *data = NULL;
-        rot_13_private_t *priv = NULL;
+    data_t *data = NULL;
+    rot_13_private_t *priv = NULL;
 
-        if (!this->children || this->children->next) {
-                gf_log ("rot13", GF_LOG_ERROR,
-                        "FATAL: rot13 should have exactly one child");
-                return -1;
-        }
+    if (!this->children || this->children->next) {
+        gf_log ("rot13", GF_LOG_ERROR,
+            "FATAL: rot13 should have exactly one child");
+        return -1;
+    }
 
-        if (!this->parents) {
-                gf_log (this->name, GF_LOG_WARNING,
-                        "dangling volume. check volfile ");
-        }
+    if (!this->parents) {
+        gf_log (this->name, GF_LOG_WARNING,
+            "dangling volume. check volfile ");
+    }
 
-        priv = GF_CALLOC (sizeof (rot_13_private_t), 1, 0);
-        if (!priv)
-                return -1;
+    priv = GF_CALLOC (sizeof (rot_13_private_t), 1, 0);
+    if (!priv)
+        return -1;
 ```
 
 At the very top, we see the function signature -- we get a pointer to the
@@ -273,20 +274,20 @@ To finish our tour of standard initialization/termination, let's look at the
 end of `init` and the beginning of `fini`:
 
 ```
-        this->private = priv;
-        gf_log ("rot13", GF_LOG_DEBUG, "rot13 xlator loaded");
-        return 0;
+    this->private = priv;
+    gf_log ("rot13", GF_LOG_DEBUG, "rot13 xlator loaded");
+    return 0;
 }
 
 void
 fini (xlator_t *this)
 {
-        rot_13_private_t *priv = this->private;
+    rot_13_private_t *priv = this->private;
 
-        if (!priv)
-                return;
-        this->private = NULL;
-        GF_FREE (priv);
+    if (!priv)
+        return;
+    this->private = NULL;
+    GF_FREE (priv);
 ```
 
 At the end of init we're just storing our private-data pointer in the `priv`
@@ -336,20 +337,21 @@ TARGET  = rot-13.so
 OBJECTS = rot-13.o
 
 # Change these to match your environment.
-GLFS_SRC = /play/glusterfs
-GLFS_LIB = /opt/glusterfs/3git/lib64
+GLFS_SRC = /srv/glusterfs
+GLFS_LIB = /usr/lib64
 HOST_OS  = GF_LINUX_HOST_OS
 
 # You shouldn't need to change anything below here.
 
 CFLAGS  = -fPIC -Wall -O0 -g \
-          -DHAVE_CONFIG_H -D_FILE_OFFSET_BITS=64 -D_GNU_SOURCE -D$(HOST_OS) \
-          -I$(GLFS_SRC) -I$(GLFS_SRC)/libglusterfs/src \
-          -I$(GLFS_SRC)/contrib/uuid
-LDFLAGS = -shared -nostartfiles -L$(GLFS_LIB) -lglusterfs -lpthread
+      -DHAVE_CONFIG_H -D_FILE_OFFSET_BITS=64 -D_GNU_SOURCE \
+      -D$(HOST_OS) -I$(GLFS_SRC) -I$(GLFS_SRC)/contrib/uuid \
+      -I$(GLFS_SRC)/libglusterfs/src
+LDFLAGS = -shared -nostartfiles -L$(GLFS_LIB) -lglusterfs \
+      -lpthread
 
 $(TARGET): $(OBJECTS)
-        $(CC) $(OBJECTS) $(LDFLAGS) -o $(TARGET)
+    $(CC) $(OBJECTS) $(LDFLAGS) -o $(TARGET)
 ```
 
 Yes, it's still Linux-specific. Mea culpa. As you can see, we're sticking with
@@ -358,7 +360,7 @@ the `rot-13` example, so you can just copy the files from
 `make` and you should be rewarded with a nice little `.so` file.
 
 ```
-[jeff@gfs-i8c-01 xlator_example]$ ls -l rot-13.so
+xlator_example$ ls -l rot-13.so
 -rwxr-xr-x. 1 jeff jeff 40784 Nov 16 16:41 rot-13.so
 ```
 
@@ -369,9 +371,11 @@ on our system, so that it doesn't stomp on the installed version (not that
 you'd ever want to use that anyway).
 
 ```
-[root@gfs-i8c-01 xlator_example]# ls /opt/glusterfs/3git/lib64/glusterfs/3git/xlator/encryption/
-crypt.so  crypt.so.0  crypt.so.0.0.0  rot-13.so  rot-13.so.0  rot-13.so.0.0.0
-[root@gfs-i8c-01 xlator_example]# cp rot-13.so /opt/glusterfs/3git/lib64/glusterfs/3git/xlator/encryption/my-rot-13.so
+xlator_example# ls /usr/lib64/glusterfs/3git/xlator/encryption/
+crypt.so crypt.so.0 crypt.so.0.0.0 rot-13.so rot-13.so.0
+rot-13.so.0.0.0
+xlator_example# cp rot-13.so \
+    /usr/lib64/glusterfs/3git/xlator/encryption/my-rot-13.so
 ```
 
 These paths represent the current Gluster filesystem layout, which is likely to
@@ -384,7 +388,7 @@ volfile. Here's just about the simplest volfile you'll ever see.
 ```
 volume my-posix
     type storage/posix
-    option directory /play/export
+    option directory /srv/export
 end-volume
 
 volume my-rot13
@@ -393,7 +397,7 @@ volume my-rot13
 end-volume
 ```
 
-All we have here is a basic brick using `/play/export` for its data, and then
+All we have here is a basic brick using `/srv/export` for its data, and then
 an instance of our translator layered on top -- no client or server is
 necessary for what we're doing, and the system will automatically push a
 mount/fuse translator on top if there's no server translator. To try this out,
@@ -401,7 +405,7 @@ all we need is the following command (assuming the directories involved already
  exist).
 
 ```
-[jeff@gfs-i8c-01 xlator_example]$ glusterfs --debug -f my.vol /play/import
+xlator_example$ glusterfs --debug -f my.vol /srv/import
 ```
 
 You should be rewarded with a whole lot of log output, including the text of
@@ -410,18 +414,18 @@ go to another window on the same machine, you can see that you have a new
 filesystem mounted.
 
 ```
-[jeff@gfs-i8c-01 ~]$ df /play/import
-Filesystem           1K-blocks      Used Available Use% Mounted on
-/play/xlator_example/my.vol
-                     114506240   2706176 105983488   3% /play/import
+~$ df /srv/import
+Filesystem   1K-blocks     Used    Available Use% Mounted on
+/srv/xlator_example/my.vol
+             114506240     2706176 105983488   3% /srv/import
 ```
 
-Just for fun, write something into a file in `/play/import`, then look at the
-corresponding file in `/play/export` to see it all `rot-13`'ed for you.
+Just for fun, write something into a file in `/srv/import`, then look at the
+corresponding file in `/srv/export` to see it all `rot-13`'ed for you.
 
 ```
-[jeff@gfs-i8c-01 ~]$ echo hello > /play/import/a_file
-[jeff@gfs-i8c-01 ~]$ cat /play/export/a_file
+~$ echo hello > /srv/import/a_file
+~$ cat /srv/export/a_file
 uryyb
 ```
 
@@ -440,26 +444,28 @@ time to run one and actually watch it work. The best way to do this is good
 old-fashioned `gdb`, as follows (using some of the examples from last time).
 
 ```
-[root@gfs-i8c-01 xlator_example]# gdb glusterfs
+xlator_example# gdb glusterfs
 GNU gdb (GDB) Red Hat Enterprise Linux (7.2-50.el6)
 ...
-(gdb) r --debug -f my.vol /play/import
-Starting program: /usr/sbin/glusterfs --debug -f my.vol /play/import
+(gdb) r --debug -f my.vol /srv/import
+Starting program: /usr/sbin/glusterfs --debug -f my.vol /srv/import
 ...
-[2011-11-23 11:23:16.495516] I [fuse-bridge.c:2971:fuse_init] 0-glusterfs-fuse: FUSE inited with protocol versions: glusterfs 7.13 kernel 7.13
+[2011-11-23 11:23:16.495516] I [fuse-bridge.c:2971:fuse_init]
+    0-glusterfs-fuse: FUSE inited with protocol versions:
+    glusterfs 7.13 kernel 7.13
 ```
 
 If you get to this point, your glusterfs client process is already running. You
 can go to another window to see the mountpoint, do file operations, etc.
 
 ```
-[root@gfs-i8c-01 ~]# df /play/import
-Filesystem           1K-blocks      Used Available Use% Mounted on
+~# df /srv/import
+Filesystem   1K-blocks     Used    Available Use% Mounted on
 /root/xlator_example/my.vol
-                     114506240   2643968 106045568   3% /play/import
-[root@gfs-i8c-01 ~]# ls /play/import
+             114506240     2643968 106045568   3% /srv/import
+~# ls /srv/import
 a_file
-[root@gfs-i8c-01 ~]# cat /play/import/a_file
+~# cat /srv/import/a_file
 hello
 ```
 
@@ -468,15 +474,24 @@ Now let's interrupt the process and see where we are.
 ```
 ^C
 Program received signal SIGINT, Interrupt.
-0x0000003a0060b3dc in pthread_cond_wait@@GLIBC_2.3.2 () from /lib64/libpthread.so.0
+0x0000003a0060b3dc in pthread_cond_wait@@GLIBC_2.3.2 ()
+                   from /lib64/libpthread.so.0
 (gdb) info threads
-  5 Thread 0x7fffeffff700 (LWP 27206)  0x0000003a002dd8c7 in readv ()
-   from /lib64/libc.so.6
-  4 Thread 0x7ffff50e3700 (LWP 27205)  0x0000003a0060b75b in pthread_cond_timedwait@@GLIBC_2.3.2 () from /lib64/libpthread.so.0
-  3 Thread 0x7ffff5f02700 (LWP 27204)  0x0000003a0060b3dc in pthread_cond_wait@@GLIBC_2.3.2 () from /lib64/libpthread.so.0
-  2 Thread 0x7ffff6903700 (LWP 27203)  0x0000003a0060f245 in sigwait ()
-   from /lib64/libpthread.so.0
-* 1 Thread 0x7ffff7957700 (LWP 27196)  0x0000003a0060b3dc in pthread_cond_wait@@GLIBC_2.3.2 () from /lib64/libpthread.so.0
+  5 Thread 0x7fffeffff700 (LWP 27206)  0x0000003a002dd8c7
+    in readv ()
+    from /lib64/libc.so.6
+  4 Thread 0x7ffff50e3700 (LWP 27205)  0x0000003a0060b75b
+    in pthread_cond_timedwait@@GLIBC_2.3.2 ()
+    from /lib64/libpthread.so.0
+  3 Thread 0x7ffff5f02700 (LWP 27204)  0x0000003a0060b3dc
+    in pthread_cond_wait@@GLIBC_2.3.2 ()
+    from /lib64/libpthread.so.0
+  2 Thread 0x7ffff6903700 (LWP 27203)  0x0000003a0060f245
+    in sigwait ()
+    from /lib64/libpthread.so.0
+* 1 Thread 0x7ffff7957700 (LWP 27196)  0x0000003a0060b3dc
+    in pthread_cond_wait@@GLIBC_2.3.2 ()
+    from /lib64/libpthread.so.0
 ```
 
 Like any non-toy server, this one has multiple threads. What are they all
@@ -504,13 +519,14 @@ Continuing.
 At this point we go into our other window and do something that will involve a write.
 
 ```
-[root@gfs-i8c-01 ~]# echo goodbye > /play/import/another_file
+~# echo goodbye > /srv/import/another_file
 (back to the first window)
 [Switching to Thread 0x7fffeffff700 (LWP 27206)]
 
-Breakpoint 1, rot13_writev (frame=0x7ffff6e4402c, this=0x638440, fd=0x7ffff409802c,
-    vector=0x7fffe8000cd8, count=1, offset=0, iobref=0x7fffe8001070) at rot-13.c:119
-119             rot_13_private_t *priv = (rot_13_private_t *)this->private;
+Breakpoint 1, rot13_writev (frame=0x7ffff6e4402c, this=0x638440,
+    fd=0x7ffff409802c, vector=0x7fffe8000cd8, count=1, offset=0,
+    iobref=0x7fffe8001070) at rot-13.c:119
+119   rot_13_private_t *priv = (rot_13_private_t *)this->private;
 ```
 
 Remember how we built with debugging symbols enabled and no optimization? That
@@ -542,7 +558,7 @@ written, like this.
 (gdb) p vector[0]
 $2 = {iov_base = 0x7ffff7936000, iov_len = 8}
 (gdb) x/s 0x7ffff7936000
-0x7ffff7936000:  "goodbye\n"
+0x7ffff7936000:     "goodbye\n"
 ```
 
 It's not always safe to view this data as a string, because it might just as
@@ -551,21 +567,21 @@ and convenient. With that knowledge, let's step through things a bit.
 
 ```
 (gdb) s
-120             if (priv->encrypt_write)
+120        if (priv->encrypt_write)
 (gdb)
-121                     rot13_iovec (vector, count);
+121            rot13_iovec (vector, count);
 (gdb)
 rot13_iovec (vector=0x7fffe8000cd8, count=1) at rot-13.c:57
-57              for (i = 0; i < count; i++) {
+57        for (i = 0; i < count; i++) {
 (gdb)
-58                      rot13 (vector[i].iov_base, vector[i].iov_len);
+58            rot13 (vector[i].iov_base, vector[i].iov_len);
 (gdb)
 rot13 (buf=0x7ffff7936000 "goodbye\n", len=8) at rot-13.c:45
-45              for (i = 0; i < len; i++) {
+45        for (i = 0; i < len; i++) {
 (gdb)
-46                      if (buf[i] >= 'a' && buf[i] <= 'z')
+46            if (buf[i] >= 'a' && buf[i] <= 'z')
 (gdb)
-47                              buf[i] = 'a' + ((buf[i] - 'a' + 13) % 26);
+47                buf[i] = 'a' + ((buf[i] - 'a' + 13) % 26);
 ```
 
 Here we've stepped into `rot13_iovec`, which iterates through our vector
@@ -575,14 +591,17 @@ stuff, so  let's skip to the next interesting bit.
 
 ```
 (gdb) fin
-Run till exit from #0  rot13 (buf=0x7ffff7936000 "goodbye\n", len=8) at rot-13.c:47
+Run till exit from #0  rot13 (buf=0x7ffff7936000 "goodbye\n",
+    len=8) at rot-13.c:47
 rot13_iovec (vector=0x7fffe8000cd8, count=1) at rot-13.c:57
-57              for (i = 0; i < count; i++) {
+57        for (i = 0; i < count; i++) {
 (gdb) fin
-Run till exit from #0  rot13_iovec (vector=0x7fffe8000cd8, count=1) at rot-13.c:57
-rot13_writev (frame=0x7ffff6e4402c, this=0x638440, fd=0x7ffff409802c,
-    vector=0x7fffe8000cd8, count=1, offset=0, iobref=0x7fffe8001070) at rot-13.c:123
-123             STACK_WIND (frame,
+Run till exit from #0  rot13_iovec (vector=0x7fffe8000cd8,
+    count=1) at rot-13.c:57
+rot13_writev (frame=0x7ffff6e4402c, this=0x638440,
+    fd=0x7ffff409802c, vector=0x7fffe8000cd8, count=1,
+    offset=0, iobref=0x7fffe8001070) at rot-13.c:123
+123        STACK_WIND (frame,
 (gdb) b 129
 Breakpoint 2 at 0x7ffff50e4f35: file rot-13.c, line 129.
 (gdb) b rot13_writev_cbk
@@ -594,21 +613,25 @@ So we've set breakpoints on both the callback and the statement following the
 `STACK_WIND`. Which one will we hit first?
 
 ```
-Breakpoint 3, rot13_writev_cbk (frame=0x7ffff6e4402c, cookie=0x7ffff6e440d8,
-    this=0x638440, op_ret=8, op_errno=0, prebuf=0x7fffefffeca0,
-    postbuf=0x7fffefffec30) at rot-13.c:106
-106             STACK_UNWIND_STRICT (writev, frame, op_ret, op_errno, prebuf, postbuf);
+Breakpoint 3, rot13_writev_cbk (frame=0x7ffff6e4402c,
+    cookie=0x7ffff6e440d8, this=0x638440, op_ret=8, op_errno=0,
+    prebuf=0x7fffefffeca0, postbuf=0x7fffefffec30)
+    at rot-13.c:106
+106  STACK_UNWIND_STRICT (writev, frame, op_ret, op_errno,
+                          prebuf, postbuf);
 (gdb) bt
-#0  rot13_writev_cbk (frame=0x7ffff6e4402c, cookie=0x7ffff6e440d8, this=0x638440,
-    op_ret=8, op_errno=0, prebuf=0x7fffefffeca0, postbuf=0x7fffefffec30)
+#0  rot13_writev_cbk (frame=0x7ffff6e4402c,
+    cookie=0x7ffff6e440d8, this=0x638440, op_ret=8, op_errno=0,
+    prebuf=0x7fffefffeca0, postbuf=0x7fffefffec30)
     at rot-13.c:106
 #1  0x00007ffff52f1b37 in posix_writev (frame=0x7ffff6e440d8,
     this=<value optimized out>, fd=<value optimized out>,
-    vector=<value optimized out>, count=1, offset=<value optimized out>,
-    iobref=0x7fffe8001070) at posix.c:2217
-#2  0x00007ffff50e513e in rot13_writev (frame=0x7ffff6e4402c, this=0x638440,
-    fd=0x7ffff409802c, vector=0x7fffe8000cd8, count=1, offset=0,
-    iobref=0x7fffe8001070) at rot-13.c:123
+    vector=<value optimized out>, count=1,
+    offset=<value optimized out>, iobref=0x7fffe8001070)
+    at posix.c:2217
+#2  0x00007ffff50e513e in rot13_writev (frame=0x7ffff6e4402c,
+    this=0x638440, fd=0x7ffff409802c, vector=0x7fffe8000cd8,
+    count=1, offset=0, iobref=0x7fffe8001070) at rot-13.c:123
 ```
 
 Surprise! We're in `rot13_writev_cbk` now, called (indirectly) while we're