From a2477ad9d38097348b18ed8f3614951aef8b97ef Mon Sep 17 00:00:00 2001
From: Giorgio Calderone <giorgio.calderone@gmail.com>
Date: Thu, 2 Apr 2020 15:24:19 +0200
Subject: [PATCH] Docstrings updated

---
 docs/make.jl         |   1 +
 docs/src/advanced.md |   2 +-
 docs/src/style.md    | 102 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 104 insertions(+), 1 deletion(-)
 create mode 100644 docs/src/style.md

diff --git a/docs/make.jl b/docs/make.jl
index 30aae92..7dbe79c 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -9,6 +9,7 @@ makedocs(sitename="Gnuplot.jl",
              "Installation" => "install.md",
              "Basic usage" => "basic.md",
              "Advanced usage" => "advanced.md",
+             "Style guide" => "style.md",
              "Gnuplot terminals" => "terminals.md",
              "Examples" => "examples.md",
              "API" => "api.md"
diff --git a/docs/src/advanced.md b/docs/src/advanced.md
index b470d41..58d895d 100644
--- a/docs/src/advanced.md
+++ b/docs/src/advanced.md
@@ -228,7 +228,7 @@ gpexec("print GPVAL_TERM")
 gpexec("set term unknown")  #hide
 ```
 
-You may also provide a session ID as first argument (see [Multiple sessions](@ref), to redirect the command to a specific session.
+You may also provide a session ID as first argument (see [Multiple sessions](@ref)) to redirect the command to a specific session.
 
 
 ## Dry sessions
diff --git a/docs/src/style.md b/docs/src/style.md
new file mode 100644
index 0000000..de99380
--- /dev/null
+++ b/docs/src/style.md
@@ -0,0 +1,102 @@
+# Style Guide
+
+The **Gnuplot.jl** loose syntax allows to create a plot using very different approaches.  While this was one of the initial purposes for the package, it may lead to decreased code readability if not used judiciously.
+
+Here I will summarize a few, non-mandatory, guidelines which allows to maintain a neat syntax and a high readability:
+
+### 1 - Use macros without parentheses and commas:
+The two most important symbols exported by the package (`@gp` and `@gsp`) are macros.  As such they are supposed to be invoked without parentheses and commas.  E.g. use:
+```julia
+@gp x y "with lines"
+```
+in place of 
+```julia
+@gp(x, y, "with lines")
+```
+
+If you have very long lines you may split them in multiple statements using the `:-` symbol, which resembles both hyphenation in natural language and indentation for the plot-producing code:
+```julia
+@gp    "set grid" :- 
+@gp :- x y "with lines"
+```
+Note that the trailing `:-` symbol is not mandatory.  If omitted, the plot will be updated at each statement (rather than at the last one).
+
+
+### 2 - Use keywords in place of gnuplot commands:
+
+As discussed in [Keywords for common commands](@ref) several commonly used gnuplot commands can be replaced with a keyword.  E.g. you can use
+```julia
+@gp ... xrange=[-1,5] ...
+```
+in place of 
+```julia
+@gp ... "set xrange [-1:5]" ...
+```
+This help reducing the number of strings used in the code, as well as the associated interpolating characters (`$`), and results in a more concise syntax.
+
+
+
+### 3 - Use abbreviations for commands and keywords:
+
+Many gnuplot commands, as well as all keywords (see [Keywords for common commands](@ref), can be abbreviated as long as the abbreviation is unambiguous.  E.g., the following code:
+```julia
+@gp    "set grid" "set key left" "set logscale y"
+@gp :- "set title 'Plot title'" "set label 'X label'" "set xrange [0:*]"
+@gp :- x y "with lines"
+```
+can be replaced with a shorter version:
+```julia
+@gp    "set grid" k="left" ylog=true
+@gp :- tit="Plot title" xlab="X label" xr=[0,NaN]
+@gp :- x y "w l"
+```
+Besides being more idiomatic, the possibility to exploit abbreviations is of great importance when performing interactive data exploration.
+
+Moreover, in many gnuplot examples and documentation it is very common to use abbreviations (i.e. `w l` in place of `with lines`) so there is no reason to avoid them in **Gnuplot.jl**.
+
+
+
+### 4 - If possible, follow the *commands* -> *data* + *plot specs* order
+
+The two following examples produce exactly the same plot:
+```julia
+x = -10.:10
+@gp    "set grid" "set multiplot layout 2,1" 
+@gp :- 1 x x.^2 "w l t 'f(x) = x^2"  # first plot
+@gp :- 2 x x.^3 "w l t 'f(x) = x^3"  # second plot
+```
+and
+```julia
+@gp    2 x x.^3 "w l t 'f(x) = x^3"  # second plot
+@gp :- 1 x x.^2 "w l t 'f(x) = x^2"  # first plot
+@gp :- "set grid" "set multiplot layout 2,1"
+```
+However, the first form appears more *logical* and easy to follow.
+
+In analogy with previous example, even on single plot, the following form
+```julia
+@gp    "set grid"
+@gp :- x x.^2 "w l t 'f(x) = x^2"
+```
+should be preferred over
+```julia
+@gp    x x.^2 "w l t 'f(x) = x^2"
+@gp :- "set grid"
+```
+even if the output is exactly the same.
+
+
+### 5 - Join multiple command strings:
+
+Instead of specifying several commands as strings
+```julia
+@gp :- "set key off"  "set auto fix"  "set size square"
+@gp :- "set offsets graph .05, graph .05, graph .05, graph .05"
+@gp :- "set border lw 1 lc rgb 'white'"
+```
+join them in a single string using triple quotes and `;`
+```julia
+@gp :- """set key off;  set auto fix;  set size square;
+          set offsets graph .05, graph .05, graph .05, graph .05;
+          set border lw 1 lc rgb 'white'; """
+```