readthedocs

10 files changed, 432 insertions, 391 deletions

diff --git a/README.md b/README.md
index 7e63e04..25f4c3c 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,22 @@
-<a name="gnuplot.dok"/>
+<a name="gnuplot.dok"></a>
 # Plotting Package Manual with Gnuplot #
 
-A plotting package to visualize [Tensor](..:torch:index#Tensor) objects.
+A plotting package to visualize [Tensor](https://github.com/torch/torch7/blob/master/doc/tensor.md#tensor) objects.
 Functions fall into several types of categories:
-  * [Line plotting](#gnuplot.line.dok)
-  * [Plotting 3D surfaces](#gnuplot.surface.dok)
-  * [Plotting matrices as images](#gnuplot.image.dok)
-  * [Plotting histogram of data](#gnuplot.histogram.dok)
-  * [Plotting directly into files](#gnuplot.files.dok)
-  * [Common operations to decorate plots](#gnuplot.commons.dok)
 
+  * [Plotting lines](doc/plotline.md#gnuplot.line.dok)
+  * [Plotting matrices](doc/plotmatrix.md#gnuplot.image.dok)
+  * [Plotting surfaces](doc/plotsurface.md#gnuplot.surface.dok)
+  * [Plotting histograms](doc/plothistogram.md#gnuplot.histogram.dok)
+  * [Saving to Files](doc/file.md#gnuplot.files.dok)
+  * [Common operations](doc/decorateplot.md#gnuplot.commons.dok)
+  
 The plotting package currently uses [gnuplot](http://gnuplot.info) as
 a backend to display data. In particular, `Gnuplot` version `4.4`
 or above is suggested for full support of all functionality.
 
 By default, the plot package will search for terminal in following order:
+
   * ` windows ` terminal if operating system is windows
   * ` wxt `, ` qt `, ` x11 `  terminal if operating system is linux
   * ` aqua `, `wxt`, ` qt `, ` x11 ` terminal if operating system is mac
@@ -27,387 +29,5 @@ rotating...
 
 The `Gnuplot` port uses `pipes` to communicate with `gnuplot`,
 therefore each plotting session is persistent and additional commands
-can be sent. For advanced users [gnuplot.raw](#gnuplot.raw)
+can be sent. For advanced users [gnuplot.raw](doc/common.md#gnuplot.raw)
 provides a free form interface to gnuplot.
-
-<a name="gnuplot.custom.dok"/>
-## Customizing Gnuplot Defaults ##
-
-The default styles of gnuplot can be customized using a personal `.gnuplot` file
-located in the users home directory. A sample file is given below as a sample. You can
-paste the contents into `$HOME/.gnuplot` file and gnuplot will use the styles
-specified in this file.
-
-```
-##### Modified version of the sample given in
-##### http://www.guidolin.net/blog/files/2010/03/gnuplot
-
-
-set macro
-
-#####  Color Palette by Color Scheme Designer
-#####  Palette URL: http://colorschemedesigner.com/#3K40zsOsOK-K-
-
-
-   blue_000 = "#A9BDE6" # = rgb(169,189,230)
-   blue_025 = "#7297E6" # = rgb(114,151,230)
-   blue_050 = "#1D4599" # = rgb(29,69,153)
-   blue_075 = "#2F3F60" # = rgb(47,63,96)
-   blue_100 = "#031A49" # = rgb(3,26,73)
-
-   green_000 = "#A6EBB5" # = rgb(166,235,181)
-   green_025 = "#67EB84" # = rgb(103,235,132)
-   green_050 = "#11AD34" # = rgb(17,173,52)
-   green_075 = "#2F6C3D" # = rgb(47,108,61)
-   green_100 = "#025214" # = rgb(2,82,20)
-
-   red_000 = "#F9B7B0" # = rgb(249,183,176)
-   red_025 = "#F97A6D" # = rgb(249,122,109)
-   red_050 = "#E62B17" # = rgb(230,43,23)
-   red_075 = "#8F463F" # = rgb(143,70,63)
-   red_100 = "#6D0D03" # = rgb(109,13,3)
-
-   brown_000 = "#F9E0B0" # = rgb(249,224,176)
-   brown_025 = "#F9C96D" # = rgb(249,201,109)
-   brown_050 = "#E69F17" # = rgb(230,159,23)
-   brown_075 = "#8F743F" # = rgb(143,116,63)
-   brown_100 = "#6D4903" # = rgb(109,73,3)
-
-   grid_color = "#d5e0c9"
-   text_color = "#222222"
-
-   my_font = "SVBasic Manual, 12"
-   my_export_sz = "1024,768"
-
-   my_line_width = "2"
-   my_axis_width = "1"
-   my_ps = "1.5"
-   my_font_size = "14"
-
-# must convert font fo svg and ps
-# set term svg  size @my_export_sz fname my_font fsize my_font_size enhanced dynamic rounded
-# set term png  size @my_export_sz large font my_font
-# set term jpeg size @my_export_sz large font my_font
-# set term wxt enhanced font my_font
-
-set style data linespoints
-set style function lines
-set pointsize my_ps
-
-set style line 1  linecolor rgbcolor blue_050  linewidth @my_line_width pt 7
-set style line 2  linecolor rgbcolor green_050 linewidth @my_line_width pt 5
-set style line 3  linecolor rgbcolor red_050   linewidth @my_line_width pt 9
-set style line 4  linecolor rgbcolor brown_050 linewidth @my_line_width pt 13
-set style line 5  linecolor rgbcolor blue_025  linewidth @my_line_width pt 11
-set style line 6  linecolor rgbcolor green_025 linewidth @my_line_width pt 7
-set style line 7  linecolor rgbcolor red_025   linewidth @my_line_width pt 5
-set style line 8  linecolor rgbcolor brown_025 linewidth @my_line_width pt 9
-set style line 9  linecolor rgbcolor blue_075  linewidth @my_line_width pt 13
-set style line 10 linecolor rgbcolor green_075 linewidth @my_line_width pt 11
-set style line 11 linecolor rgbcolor red_075   linewidth @my_line_width pt 7
-set style line 12 linecolor rgbcolor brown_075 linewidth @my_line_width pt 5
-set style line 13 linecolor rgbcolor blue_100  linewidth @my_line_width pt 9
-set style line 14 linecolor rgbcolor green_100 linewidth @my_line_width pt 13
-set style line 15 linecolor rgbcolor red_100   linewidth @my_line_width pt 11
-set style line 16 linecolor rgbcolor brown_100 linewidth @my_line_width pt 7
-set style line 17 linecolor rgbcolor "#224499" linewidth @my_line_width pt 5
-
-## plot 1,2,3,4,5,6,7,8,9
-set style increment user
-set style arrow 1 filled
-
-## used for bar chart borders
-set style fill solid 0.5
-
-set size noratio
-set samples 300
-
-set border 31 lw @my_axis_width lc rgb text_color
-```
-
-<a name="gnuplot.line.dok"/>
-## Line Plotting ##
-
-Line plotting functionality covers many configurations from simplest
-case of plotting a single vector to displaying multiple lines at once
-with custom line specifictions.
-
-<a name="gnuplot.plot"/>
-### gnuplot.plot(x) ###
-Plot vector ` x ` using dots of first default `Gnuplot` type.
-
-```lua
-x=torch.linspace(-2*math.pi,2*math.pi)
-gnuplot.plot(torch.sin(x))
-```
-![](doc/plot_x.png)
-
-In more general form, plot vector `y` vs `x` using the format
-specified. The possible entries of format string can be:
-  * `.` for dots
-  * `+` for points
-  * `-` for lines
-  * `+-` for points and lines
-  * `~` for using smoothed lines with cubic interpolation
-  * `|` for using boxes
-  * `v` for drawing vector fiels. (In this case, `x` and `y` have to be two column vectors `(x, xdelta)`, `(y, ydelta)`)
-  * custom string, one can also pass custom strings to use full capability of gnuplot.
-
-```lua
-x = torch.linspace(-2*math.pi,2*math.pi)
-gnuplot.plot('Sin',x/math.pi,torch.sin(x),'|')
-```
-![](doc/plot_xyf.png)
-
-To plot multiple curves at a time, one can pass each plot struct in a table.
-
-```lua
-x = torch.linspace(-2*math.pi,2*math.pi)
-gnuplot.plot({'Cos',x/math.pi,torch.cos(x),'~'},{'Sin',x/math.pi,torch.sin(x),'|'})
-```
-![](doc/plot_sincos.png)
-
-One can pass data with multiple columns and use custom gnuplot style strings too. When multi-column data
-is used, the first column is assumed to be the `x` values and the rest of the columns are separate `y` series.
-
-```lua
-x = torch.linspace(-5,5)
-y = torch.sin(x)
-yp = y+0.3+torch.rand(x:size())*0.1
-ym = y-(torch.rand(x:size())*0.1+0.3)
-yy = torch.cat(x,ym,2)
-yy = torch.cat(yy,yp,2)
-gnuplot.plot({yy,' filledcurves'},{x,yp,'lines ls 1'},{x,ym,'lines ls 1'},{x,y,'lines ls 1'})
-```
-![](doc/plot_filled.png)
-
-<a name="gnuplot.surface.dok"/>
-## Plotting 3D Surfaces ##
-
-Surface plotting creates a 3D surface plot of a given matrix `z`. Entries
-of `z` are used as height values. It is also possible to specify `x` and
-`y` locations corresponding to each point in `z` . If a terminal with
-interactive capabilities is being used by `Gnuplot` backend (like `x11` or
-`wxt` or `qt`), then rotating, zooming is also possible.
-
-<a name="gnuplot.splot"/>
-### gnuplot.splot(z) ###
-
-Plot surface ` z ` in 3D.
-```lua
-x = torch.linspace(-1,1)
-xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x)
-xx = xx*math.pi*6
-gnuplot.splot(torch.sin(xx))
-```
-![](doc/plot_splot.png)
-
-It is also possible to specify the `x` and `y` locations of each
-point in `z` by `gnuplot.splot(x,y,z)`. In this `x` and `y` has
-to be the same shape as `z`.
-
-One can also display multiple surfaces at a time.
-
-```lua
-x = torch.linspace(-1,1)
-xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x)
-xx = xx*math.pi*2
-gnuplot.splot({torch.sin(xx)},{torch.sin(xx)+2})
-```
-![](doc/plot_splot2.png)
-
-<a name="gnuplot.image.dok"/>
-## Plotting Matrices as Images ##
-
-A given matrix can be plotted using 2D contour plot on a surface.
-
-<a name="gnuplot.imagesc"/>
-### gnuplot.imagesc(z, ['color' or 'gray']) ###
-
-Plot surface ` z ` using contour plot. The second argument defines
-the color palette for the display. By default, grayscale colors are
-used, however, one can also use any color palette available in
-`Gnuplot`.
-
-```lua
-x = torch.linspace(-1,1)
-xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x)
-xx = xx*math.pi*6
-gnuplot.imagesc(torch.sin(xx),'color')
-```
-![](doc/plot_imagesc.png)
-
-<a name="gnuplot.histogram.dok"/>
-## Histograms ##
-
-Given a tensor, the distribution of values can be plotted using
-`gnuplot.hist` function.
-
-<a name="gnuplot.hist"/>
-### gnuplot.hist(x, [nbins, min, max]) ###
-
-Plot the histogram of values in `N-D` tensor `x`, optionally using `nbins`
-number of bins and only using values between `min` and `max`.
-
-```lua
-gnuplot.hist(torch.randn(100000),100)
-```
-![](doc/plot_hist.png)
-
-<a name="gnuplot.files.dok"/>
-## Plotting Directly into Files ##
-
-Any of the above plotting utilities can also be used for directly plotting
-into `eps` or `png` files, or `pdf` files if your gnuplot installation
-allows. A final gnuplot.plotflush() command ensures that all output is
-written to the file properly.
-
-```lua
-gnuplot.epsfigure('test.eps')
-gnuplot.plot({'Sin Curve',torch.sin(torch.linspace(-5,5))})
-gnuplot.xlabel('X')
-gnuplot.ylabel('Y')
-gnuplot.plotflush()
-```
-
-<a name="gnuplot.commons.dok"/>
-## Common Operations ##
-
-It is possible to manage multiple plots at a time, printing plots to
-png, eps or pdf files or creating plots directly on png or eps or pdf files.
-
-There are also several handy operations for decorating plots which are
-common to many of the plotting functions.
-
-
-<a name="gnuplot.setgnuplotexe"/>
-### gnuplot.setgnuplotexe(exe) ###
-
-Manually set the location of gnuplot executable.
-
-<a name="gnuplot.setterm"/>
-### gnuplot.setterm(teerm) ###
-
-Manually set the gnuplot terminal.
-
-<a name="gnuplot.closeall"/>
-### gnuplot.closeall() ###
-
-Close all gnuplot active connections. This will not be able to close
-open windows, since on the backend gnuplot also can not close windows.
-
-<a name="gnuplot.figure"/>
-### gnuplot.figure([n]) ###
-
-Select (or create) a new figure with id `n`. Note that until a plot
-command is given, the window will not be created. When `n` is
-skipped, a new figure is created with the next consecutive id.
-
-<a name="gnuplot.epsfigure"/>
-### gnuplot.epsfigure(fname) ###
-
-Creates a figure directly on the `eps` file given with
-`fname`. This uses `Gnuplot` terminal `postscript eps enhanced color`.
-
-<a name="gnuplot.pdffigure"/>
-###  gnuplot.pdffigure(fname) ###
-
-Only available if your installation of gnuplot has been compiled
-with `pdf` support enabled.
-
-Creates a figure directly on the `pdf` file given with
-`fname`. This uses `Gnuplot` terminal `pdf enhanced color`,
-or `pdfcairo enhanced color` if available.
-
-<a name="gnuplot.pngfigure"/>
-### gnuplot.pngfigure(fname) ###
-
-Creates a figure directly on the `png` file given with
-`fname`. This uses `Gnuplot` terminal `png`, or `pngcairo` if available.
-
-<a name="gnuplot.svgfigure"/>
-###  gnuplot.svgfigure(fname) ###
-
-Creates a figure directly on the `svg` file given with `fname`. This uses
-`Gnuplot` terminal `svg`.
-
-<a name="gnuplot.plotflush"/>
-### gnuplot.plotflush([n]) ###
-
-This command sends `unset output` to underlying gnuplot. Usefull for
-flushing file based terminals.
-
-<a name="gnuplot.figprint"/>
-### gnuplot.figprint(fname) ###
-
-Prints the current figure to the given file with name `fname`. Only `png`
-or `eps` files are supported by default. If your gnuplot installation
-allows, `pdf` files are also supported.
-
-<a name="gnuplot.xlabel"/>
-### gnuplot.xlabel(label) ###
-
-Sets the label of `x` axis to `label`. Only supported for gnuplot
-version 4.4 and above.
-
-<a name="gnuplot.ylabel"/>
-### gnuplot.ylabel(label) ###
-
-Sets the label of `y` axis to `label`. Only supported for gnuplot
-version 4.4 and above.
-
-<a name="gnuplot.zlabel"/>
-### gnuplot.zlabel(label) ###
-
-Sets the label of `z` axis to `label`. Only supported for gnuplot
-version 4.4 and above.
-
-<a name="gnuplot.title"/>
-### gnuplot.title(title) ###
-
-Sets the title of the plot to `title`. Only supported for gnuplot
-version 4.4 and above.
-
-<a name="gnuplot.grid"/>
-### gnuplot.grid(toggle) ###
-
-If `toggle` is `true` then a grid is displayed, else it is
-hidden. Only supported for gnuplot version 4.4 and above.
-
-<a name="gnuplot.movelegend"/>
-### gnuplot.movelegend(hloc,vloc) ###
-
-Set the location of legend key. `hloc` can be `left`, `right` or
-`center`. `vloc` can be `top`, `bottom` or `middle`. Only
-supported for gnuplot version 4.4 and above.
-
-<a name="gnuplot.axis"/>
-### gnuplot.axis(axis) ###
-
-Sets the properties of axis for the current plot.
-
-  * `auto` : auto scales the axis to fit data and plot canvas
-  * `image` : scales the axis aspect ratio so that a circle is drawn as circle.
-  * `equal` : same as `image`.
-  * `fill` : resets the aspect ratio of the plot to original values so that it fills up the canvas as good as possible.
-  * `{xmin,xmax,ymin,ymax}` : Sets the limits of x and y axes. Use an empty string (2 apostophes in a row) if you want to keep the current value.
-
-<a name="gnuplot.raw"/>
-### gnuplot.raw(command) ###
-
-This command is useful for advanced users of gnuplot. `command` is
-directly passed to gnuplot without any formatting.
-
-Let's see an example, by plotting labels for the `xtic`
-
-```lua
-LondonTemp = torch.Tensor{{9, 10, 12, 15, 18, 21, 23, 23, 20, 16, 12, 9},
-                          {5,  5,  6,  7, 10, 13, 15, 15, 13, 10,  7, 5}}
-gnuplot.plot({'High [°C]',LondonTemp[1]},{'Low [°C]',LondonTemp[2]})
-gnuplot.raw('set xtics ("Jan" 1, "Feb" 2, "Mar" 3, "Apr" 4, "May" 5, "Jun" 6, "Jul" 7, "Aug" 8, "Sep" 9, "Oct" 10, "Nov" 11, "Dec" 12)')
-gnuplot.plotflush()
-gnuplot.axis{0,13,0,''}
-gnuplot.grid(true)
-gnuplot.title('London average temperature')
-```
-![](doc/plot_raw.png)
diff --git a/doc/common.md b/doc/common.md
new file mode 100644
index 0000000..b63801d
--- /dev/null
+++ b/doc/common.md
@@ -0,0 +1,99 @@
+<a name="gnuplot.commons.dok"></a>
+## Common Operations ##
+
+It is possible to manage multiple plots at a time, printing plots to
+png, eps or pdf files or creating plots directly on png or eps or pdf files.
+
+There are also several handy operations for decorating plots which are
+common to many of the plotting functions.
+
+<a name="gnuplot.setgnuplotexe"></a>
+### gnuplot.setgnuplotexe(exe) ###
+
+Manually set the location of gnuplot executable.
+
+<a name="gnuplot.setterm"></a>
+### gnuplot.setterm(teerm) ###
+
+Manually set the gnuplot terminal.
+
+<a name="gnuplot.closeall"></a>
+### gnuplot.closeall() ###
+
+Close all gnuplot active connections. This will not be able to close
+open windows, since on the backend gnuplot also can not close windows.
+
+<a name="gnuplot.figure"></a>
+### gnuplot.figure([n]) ###
+
+Select (or create) a new figure with id `n`. Note that until a plot
+command is given, the window will not be created. When `n` is
+skipped, a new figure is created with the next consecutive id.
+
+<a name="gnuplot.xlabel"></a>
+### gnuplot.xlabel(label) ###
+
+Sets the label of `x` axis to `label`. Only supported for gnuplot
+version 4.4 and above.
+
+<a name="gnuplot.ylabel"></a>
+### gnuplot.ylabel(label) ###
+
+Sets the label of `y` axis to `label`. Only supported for gnuplot
+version 4.4 and above.
+
+<a name="gnuplot.zlabel"></a>
+### gnuplot.zlabel(label) ###
+
+Sets the label of `z` axis to `label`. Only supported for gnuplot
+version 4.4 and above.
+
+<a name="gnuplot.title"></a>
+### gnuplot.title(title) ###
+
+Sets the title of the plot to `title`. Only supported for gnuplot
+version 4.4 and above.
+
+<a name="gnuplot.grid"></a>
+### gnuplot.grid(toggle) ###
+
+If `toggle` is `true` then a grid is displayed, else it is
+hidden. Only supported for gnuplot version 4.4 and above.
+
+<a name="gnuplot.movelegend"></a>
+### gnuplot.movelegend(hloc,vloc) ###
+
+Set the location of legend key. `hloc` can be `left`, `right` or
+`center`. `vloc` can be `top`, `bottom` or `middle`. Only
+supported for gnuplot version 4.4 and above.
+
+<a name="gnuplot.axis"></a>
+### gnuplot.axis(axis) ###
+
+Sets the properties of axis for the current plot.
+
+  * `auto` : auto scales the axis to fit data and plot canvas
+  * `image` : scales the axis aspect ratio so that a circle is drawn as circle.
+  * `equal` : same as `image`.
+  * `fill` : resets the aspect ratio of the plot to original values so that it fills up the canvas as good as possible.
+  * `{xmin,xmax,ymin,ymax}` : Sets the limits of x and y axes. Use an empty string (2 apostophes in a row) if you want to keep the current value.
+
+<a name="gnuplot.raw"></a>
+### gnuplot.raw(command) ###
+
+This command is useful for advanced users of gnuplot. `command` is
+directly passed to gnuplot without any formatting.
+
+Let's see an example, by plotting labels for the `xtic`
+
+```lua
+LondonTemp = torch.Tensor{{9, 10, 12, 15, 18, 21, 23, 23, 20, 16, 12, 9},
+                          {5,  5,  6,  7, 10, 13, 15, 15, 13, 10,  7, 5}}
+gnuplot.plot({'High [°C]',LondonTemp[1]},{'Low [°C]',LondonTemp[2]})
+gnuplot.raw('set xtics ("Jan" 1, "Feb" 2, "Mar" 3, "Apr" 4, "May" 5, "Jun" 6, "Jul" 7, "Aug" 8, "Sep" 9, "Oct" 10, "Nov" 11, "Dec" 12)')
+gnuplot.plotflush()
+gnuplot.axis{0,13,0,''}
+gnuplot.grid(true)
+gnuplot.title('London average temperature')
+```
+![](plot_raw.png)
diff --git a/doc/custom.md b/doc/custom.md
new file mode 100644
index 0000000..bcbbfbe
--- /dev/null
+++ b/doc/custom.md
@@ -0,0 +1,94 @@
+<a name="gnuplot.custom.dok"></a>
+## Customizing Gnuplot Defaults ##
+
+The default styles of gnuplot can be customized using a personal `.gnuplot` file
+located in the users home directory. A sample file is given below as a sample. You can
+paste the contents into `$HOME/.gnuplot` file and gnuplot will use the styles
+specified in this file.
+
+```
+##### Modified version of the sample given in
+##### http://www.guidolin.net/blog/files/2010/03/gnuplot
+
+
+set macro
+
+#####  Color Palette by Color Scheme Designer
+#####  Palette URL: http://colorschemedesigner.com/#3K40zsOsOK-K-
+
+
+   blue_000 = "#A9BDE6" # = rgb(169,189,230)
+   blue_025 = "#7297E6" # = rgb(114,151,230)
+   blue_050 = "#1D4599" # = rgb(29,69,153)
+   blue_075 = "#2F3F60" # = rgb(47,63,96)
+   blue_100 = "#031A49" # = rgb(3,26,73)
+
+   green_000 = "#A6EBB5" # = rgb(166,235,181)
+   green_025 = "#67EB84" # = rgb(103,235,132)
+   green_050 = "#11AD34" # = rgb(17,173,52)
+   green_075 = "#2F6C3D" # = rgb(47,108,61)
+   green_100 = "#025214" # = rgb(2,82,20)
+
+   red_000 = "#F9B7B0" # = rgb(249,183,176)
+   red_025 = "#F97A6D" # = rgb(249,122,109)
+   red_050 = "#E62B17" # = rgb(230,43,23)
+   red_075 = "#8F463F" # = rgb(143,70,63)
+   red_100 = "#6D0D03" # = rgb(109,13,3)
+
+   brown_000 = "#F9E0B0" # = rgb(249,224,176)
+   brown_025 = "#F9C96D" # = rgb(249,201,109)
+   brown_050 = "#E69F17" # = rgb(230,159,23)
+   brown_075 = "#8F743F" # = rgb(143,116,63)
+   brown_100 = "#6D4903" # = rgb(109,73,3)
+
+   grid_color = "#d5e0c9"
+   text_color = "#222222"
+
+   my_font = "SVBasic Manual, 12"
+   my_export_sz = "1024,768"
+
+   my_line_width = "2"
+   my_axis_width = "1"
+   my_ps = "1.5"
+   my_font_size = "14"
+
+# must convert font fo svg and ps
+# set term svg  size @my_export_sz fname my_font fsize my_font_size enhanced dynamic rounded
+# set term png  size @my_export_sz large font my_font
+# set term jpeg size @my_export_sz large font my_font
+# set term wxt enhanced font my_font
+
+set style data linespoints
+set style function lines
+set pointsize my_ps
+
+set style line 1  linecolor rgbcolor blue_050  linewidth @my_line_width pt 7
+set style line 2  linecolor rgbcolor green_050 linewidth @my_line_width pt 5
+set style line 3  linecolor rgbcolor red_050   linewidth @my_line_width pt 9
+set style line 4  linecolor rgbcolor brown_050 linewidth @my_line_width pt 13
+set style line 5  linecolor rgbcolor blue_025  linewidth @my_line_width pt 11
+set style line 6  linecolor rgbcolor green_025 linewidth @my_line_width pt 7
+set style line 7  linecolor rgbcolor red_025   linewidth @my_line_width pt 5
+set style line 8  linecolor rgbcolor brown_025 linewidth @my_line_width pt 9
+set style line 9  linecolor rgbcolor blue_075  linewidth @my_line_width pt 13
+set style line 10 linecolor rgbcolor green_075 linewidth @my_line_width pt 11
+set style line 11 linecolor rgbcolor red_075   linewidth @my_line_width pt 7
+set style line 12 linecolor rgbcolor brown_075 linewidth @my_line_width pt 5
+set style line 13 linecolor rgbcolor blue_100  linewidth @my_line_width pt 9
+set style line 14 linecolor rgbcolor green_100 linewidth @my_line_width pt 13
+set style line 15 linecolor rgbcolor red_100   linewidth @my_line_width pt 11
+set style line 16 linecolor rgbcolor brown_100 linewidth @my_line_width pt 7
+set style line 17 linecolor rgbcolor "#224499" linewidth @my_line_width pt 5
+
+## plot 1,2,3,4,5,6,7,8,9
+set style increment user
+set style arrow 1 filled
+
+## used for bar chart borders
+set style fill solid 0.5
+
+set size noratio
+set samples 300
+
+set border 31 lw @my_axis_width lc rgb text_color
+```
diff --git a/doc/file.md b/doc/file.md
new file mode 100644
index 0000000..3fe6a1d
--- /dev/null
+++ b/doc/file.md
@@ -0,0 +1,56 @@
+<a name="gnuplot.files.dok"></a>
+## Saving Plots to Files ##
+
+Any of the above plotting utilities can also be used for directly plotting
+into `eps` or `png` files, or `pdf` files if your gnuplot installation
+allows. A final gnuplot.plotflush() command ensures that all output is
+written to the file properly.
+
+```lua
+gnuplot.epsfigure('test.eps')
+gnuplot.plot({'Sin Curve',torch.sin(torch.linspace(-5,5))})
+gnuplot.xlabel('X')
+gnuplot.ylabel('Y')
+gnuplot.plotflush()
+```
+
+<a name="gnuplot.epsfigure"></a>
+### gnuplot.epsfigure(fname) ###
+
+Creates a figure directly on the `eps` file given with
+`fname`. This uses `Gnuplot` terminal `postscript eps enhanced color`.
+
+<a name="gnuplot.pdffigure"></a>
+###  gnuplot.pdffigure(fname) ###
+
+Only available if your installation of gnuplot has been compiled
+with `pdf` support enabled.
+
+Creates a figure directly on the `pdf` file given with
+`fname`. This uses `Gnuplot` terminal `pdf enhanced color`,
+or `pdfcairo enhanced color` if available.
+
+<a name="gnuplot.pngfigure"></a>
+### gnuplot.pngfigure(fname) ###
+
+Creates a figure directly on the `png` file given with
+`fname`. This uses `Gnuplot` terminal `png`, or `pngcairo` if available.
+
+<a name="gnuplot.svgfigure"></a>
+###  gnuplot.svgfigure(fname) ###
+
+Creates a figure directly on the `svg` file given with `fname`. This uses
+`Gnuplot` terminal `svg`.
+
+<a name="gnuplot.figprint"></a>
+### gnuplot.figprint(fname) ###
+
+Prints the current figure to the given file with name `fname`. Only `png`
+or `eps` files are supported by default. If your gnuplot installation
+allows, `pdf` files are also supported.
+
+<a name="gnuplot.plotflush"></a>
+### gnuplot.plotflush([n]) ###
+
+This command sends `unset output` to underlying gnuplot. Usefull for
+flushing file based terminals.
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000..2e68116
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,33 @@
+<a name="gnuplot.dok"></a>
+# Plotting Package Manual with Gnuplot #
+
+A plotting package to visualize [Tensor](https://github.com/torch/torch7/blob/master/doc/tensor.md#tensor) objects.
+Functions fall into several types of categories:
+
+  * [Plotting lines](plotline.md#gnuplot.line.dok)
+  * [Plotting matrices](plotmatrix.md#gnuplot.image.dok)
+  * [Plotting surfaces](plotsurface.md#gnuplot.surface.dok)
+  * [Plotting histograms](plothistogram.md#gnuplot.histogram.dok)
+  * [Saving to Files](file.md#gnuplot.files.dok)
+  * [Common operations](decorateplot.md#gnuplot.commons.dok)
+
+The plotting package currently uses [gnuplot](http://gnuplot.info) as
+a backend to display data. In particular, `Gnuplot` version `4.4`
+or above is suggested for full support of all functionality.
+
+By default, the plot package will search for terminal in following order:
+
+  * ` windows ` terminal if operating system is windows
+  * ` wxt `, ` qt `, ` x11 `  terminal if operating system is linux
+  * ` aqua `, `wxt`, ` qt `, ` x11 ` terminal if operating system is mac
+
+It is also possible to manually set any terminal type using
+[gnuplot.setterm](#gnuplot.setterm). Interactivity is
+dependent on the terminal being used. By default, `x11` and ''wxt
+support'' different interactive operations like, zooming, panning,
+rotating...
+
+The `Gnuplot` port uses `pipes` to communicate with `gnuplot`,
+therefore each plotting session is persistent and additional commands
+can be sent. For advanced users [gnuplot.raw](common.md#gnuplot.raw)
+provides a free form interface to gnuplot.
diff --git a/doc/plothistogram.md b/doc/plothistogram.md
new file mode 100644
index 0000000..ac1d06a
--- /dev/null
+++ b/doc/plothistogram.md
@@ -0,0 +1,16 @@
+<a name="gnuplot.histogram.dok"></a>
+## Histograms ##
+
+Given a tensor, the distribution of values can be plotted using
+`gnuplot.hist` function.
+
+<a name="gnuplot.hist"></a>
+### gnuplot.hist(x, [nbins, min, max]) ###
+
+Plot the histogram of values in `N-D` tensor `x`, optionally using `nbins`
+number of bins and only using values between `min` and `max`.
+
+```lua
+gnuplot.hist(torch.randn(100000),100)
+```
+![](plot_hist.png)
diff --git a/doc/plotline.md b/doc/plotline.md
new file mode 100644
index 0000000..a561981
--- /dev/null
+++ b/doc/plotline.md
@@ -0,0 +1,55 @@
+<a name="gnuplot.line.dok"></a>
+## Plotting Lines ##
+
+Line plotting functionality covers many configurations from simplest
+case of plotting a single vector to displaying multiple lines at once
+with custom line specifictions.
+
+<a name="gnuplot.plot"></a>
+### gnuplot.plot(x) ###
+Plot vector ` x ` using dots of first default `Gnuplot` type.
+
+```lua
+x=torch.linspace(-2*math.pi,2*math.pi)
+gnuplot.plot(torch.sin(x))
+```
+![](plot_x.png)
+
+In more general form, plot vector `y` vs `x` using the format
+specified. The possible entries of format string can be:
+  * `.` for dots
+  * `+` for points
+  * `-` for lines
+  * `+-` for points and lines
+  * `~` for using smoothed lines with cubic interpolation
+  * `|` for using boxes
+  * `v` for drawing vector fiels. (In this case, `x` and `y` have to be two column vectors `(x, xdelta)`, `(y, ydelta)`)
+  * custom string, one can also pass custom strings to use full capability of gnuplot.
+
+```lua
+x = torch.linspace(-2*math.pi,2*math.pi)
+gnuplot.plot('Sin',x/math.pi,torch.sin(x),'|')
+```
+![](plot_xyf.png)
+
+To plot multiple curves at a time, one can pass each plot struct in a table.
+
+```lua
+x = torch.linspace(-2*math.pi,2*math.pi)
+gnuplot.plot({'Cos',x/math.pi,torch.cos(x),'~'},{'Sin',x/math.pi,torch.sin(x),'|'})
+```
+![](plot_sincos.png)
+
+One can pass data with multiple columns and use custom gnuplot style strings too. When multi-column data
+is used, the first column is assumed to be the `x` values and the rest of the columns are separate `y` series.
+
+```lua
+x = torch.linspace(-5,5)
+y = torch.sin(x)
+yp = y+0.3+torch.rand(x:size())*0.1
+ym = y-(torch.rand(x:size())*0.1+0.3)
+yy = torch.cat(x,ym,2)
+yy = torch.cat(yy,yp,2)
+gnuplot.plot({yy,' filledcurves'},{x,yp,'lines ls 1'},{x,ym,'lines ls 1'},{x,y,'lines ls 1'})
+```
+![](plot_filled.png)
diff --git a/doc/plotmatrix.md b/doc/plotmatrix.md
new file mode 100644
index 0000000..d804ae6
--- /dev/null
+++ b/doc/plotmatrix.md
@@ -0,0 +1,20 @@
+<a name="gnuplot.image.dok"></a>
+## Plotting Matrices ##
+
+A given matrix can be plotted using 2D contour plot on a surface.
+
+<a name="gnuplot.imagesc"></a>
+### gnuplot.imagesc(z, ['color' or 'gray']) ###
+
+Plot surface ` z ` using contour plot. The second argument defines
+the color palette for the display. By default, grayscale colors are
+used, however, one can also use any color palette available in
+`Gnuplot`.
+
+```lua
+x = torch.linspace(-1,1)
+xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x)
+xx = xx*math.pi*6
+gnuplot.imagesc(torch.sin(xx),'color')
+```
+![](plot_imagesc.png)
diff --git a/doc/plotsurface.md b/doc/plotsurface.md
new file mode 100644
index 0000000..5692abe
--- /dev/null
+++ b/doc/plotsurface.md
@@ -0,0 +1,34 @@
+<a name="gnuplot.surface.dok"></a>
+## Plotting 3D Surfaces ##
+
+Surface plotting creates a 3D surface plot of a given matrix `z`. Entries
+of `z` are used as height values. It is also possible to specify `x` and
+`y` locations corresponding to each point in `z` . If a terminal with
+interactive capabilities is being used by `Gnuplot` backend (like `x11` or
+`wxt` or `qt`), then rotating, zooming is also possible.
+
+<a name="gnuplot.splot"></a>
+### gnuplot.splot(z) ###
+
+Plot surface ` z ` in 3D.
+```lua
+x = torch.linspace(-1,1)
+xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x)
+xx = xx*math.pi*6
+gnuplot.splot(torch.sin(xx))
+```
+![](plot_splot.png)
+
+It is also possible to specify the `x` and `y` locations of each
+point in `z` by `gnuplot.splot(x,y,z)`. In this `x` and `y` has
+to be the same shape as `z`.
+
+One can also display multiple surfaces at a time.
+
+```lua
+x = torch.linspace(-1,1)
+xx = torch.Tensor(x:size(1),x:size(1)):zero():addr(1,x,x)
+xx = xx*math.pi*2
+gnuplot.splot({torch.sin(xx)},{torch.sin(xx)+2})
+```
+![](plot_splot2.png)
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..41e4418
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,14 @@
+site_name: gnuplot
+theme : simplex
+repo_url : https://github.com/torch/gnuplot
+use_directory_urls : false
+markdown_extensions: [extra]
+docs_dir : doc
+pages:
+- [index.md, Gnuplot]
+- [plotline.md, Plotting Lines]
+- [plotmatrix.md, Plotting Matrices]
+- [plotsurface.md, Plotting Surfaces]
+- [plothistogram.md, Plotting Histograms]
+- [file.md, Saving Plots]
+- [common.md, Common Operations]