Update docs

Author: alandefreitas

README.md

@@ -5,6 +5,8 @@
 [![Documentation](https://img.shields.io/website-up-down-green-red/http/alandefreitas.github.io/matplotplusplus.svg?label=Documentation)](https://alandefreitas.github.io/matplotplusplus/)
 [![Discussions](https://img.shields.io/website-up-down-green-red/http/alandefreitas.github.io/matplotplusplus.svg?label=Discussions)](https://github.com/alandefreitas/matplotplusplus/discussions)
 
+![](docs/img/matplotcover.png)
+
 Data visualization can help programmers and scientists identify trends in their data and efficiently communicate these results with their peers. Modern C++ is being used for a variety of scientific applications, and this environment can benefit considerably from graphics libraries that attend the typical design goals toward scientific data visualization. Besides the option of exporting results to other environments, the customary alternatives in C++ are either non-dedicated libraries that depend on existing user interfaces or bindings to other languages. **Matplot++** is a graphics library for data visualization that provides interactive plotting, means for exporting plots in high-quality formats for scientific publications, a compact syntax consistent with similar libraries, dozens of plot categories with specialized algorithms, multiple coding styles, and supports generic backends.
 
 <!-- https://github.com/bradvin/social-share-urls -->
@@ -1966,25 +1968,25 @@ A more complete example of the reactive mode would be:
 
 ```cpp
 // Reactive mode
-auto f = gcf(false);
+auto f = figure(false);
 auto ax = f->gca();
 auto p = ax->plot(ax, x, y);   // draws once
 p->color("red").line_width(2); // draws twice more
-wait();                        // pause console
+show();                        // pause console
 ```
 
-For convenience, the examples in Section [Examples](#examples) use the reactive mode. The `wait` function pauses the console until the user interacts with the plot window. If the backend is based on process pipes, because these are unidirectional, closing the window is not enough to resume. The user needs to use the console to unblock execution. A similar example is quiet mode would be
+For convenience, the examples in Section [Examples](#examples) use the reactive mode. The `show` function pauses the console until the user interacts with the plot window. If the backend is based on process pipes, because these are unidirectional, closing the window is not enough to resume. The user needs to use the console to unblock execution. A similar example is quiet mode would be
 
 ```cpp
 // Quiet mode
-auto f = gcf(true);
+auto f = figure(true);
 auto ax = f->gca();
 auto p = ax->plot(x,y);        // does not draw
 p->color("red").line_width(2); // does not draw
 f->show();                     // draw only once and pause console
 ```
 
-In this example, the figure is only updated once. The user could replace the `show` function with the `draw` function, but the window would close as soon as execution completes. It is important to use `wait()` and `show()` with caution. These functions are meant for some particular executables so that an interactive plot does not close before the user can see it. It is probably unreasonable to call these functions inside a library because the user would have to manually interfere with the execution to continue.
+In this example, the figure is only updated once. The user could replace the `show` function with the `draw` function, but the window would close as soon as execution completes. It is important to use `show()` with caution. These functions are meant for some particular executables so that an interactive plot does not close before the user can see it. It is probably unreasonable to call these functions inside a library because the user would have to manually interfere with the execution to continue.
 
 ### Method Chaining
 
@@ -2032,11 +2034,12 @@ Unfortunately, because of how templated functions work, one exception is initial
 ### Common Utilities
 
 The headers `common.h` and `colors.h` include a number of utilities we use in our examples. These include naive functions to generate and manipulate vectors and strings; handle RGBA color arrays; convert points to and from polar coordinates; read files to strings; write strings to files; calculate gradients; read, write, and manipulate images; and generate vectors with random numbers. Although some of these functions might be helpful, most functions only operate on `vector<double>` and they are not intended to be a library of utilities. The sole purpose of these algorithms is to simplify the examples.
- 
+
+<!-- START mdsplit-ignore --> 
 ## Motivation and Details
 
 If you are interested in understanding how the library works, you can read the details in the complete [article](docs/README.md). It describes the relationship between its main objects, the backend interface, how to create new plot categories, limitations, and compares this library with similar alternatives. 
-
+<!-- END mdsplit-ignore -->
 ## Integration
 
 ### Binary Packages

docs/.gitignore

@@ -1,3 +1,4 @@
 _site
 .jekyll-metadata
-Gemfile.lock
+Gemfile.lock
+!integration/build-from-source

docs/README.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: Documentation
-nav_exclude: true
+title: White Paper
+nav_exclude: false
 ---
 # Matplot++: A C++ Graphics Library for Data Visualization
 

docs/coding-styles.md

@@ -14,3 +14,6 @@ has_toc: false
 - [Method Chaining](coding-styles/method-chaining.md)
 - [Ranges](coding-styles/ranges.md)
 - [Common Utilities](coding-styles/common-utilities.md)
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/coding-styles/common-utilities.md

@@ -9,6 +9,10 @@ has_toc: false
 # Common Utilities
 
 The headers `common.h` and `colors.h` include a number of utilities we use in our examples. These include naive functions to generate and manipulate vectors and strings; handle RGBA color arrays; convert points to and from polar coordinates; read files to strings; write strings to files; calculate gradients; read, write, and manipulate images; and generate vectors with random numbers. Although some of these functions might be helpful, most functions only operate on `vector<double>` and they are not intended to be a library of utilities. The sole purpose of these algorithms is to simplify the examples.
- 
 
+<!-- START mdsplit-ignore --> 
 
+
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/coding-styles/member-vs-free-standing-functions.md

@@ -43,11 +43,14 @@ ax->plot(x, y)->color("red").line_width(2);
 my_function(ax);
 ```
 
-Both examples would generate the same plot. All free-standing functions are templated functions that use meta-programming to call the main function on the current `axes` object. If the first parameter is not an `axes_handle`, it will get an `axes_handle` from the figure registry with `gca` (Section [Axes Object](../examples/appearance/axes-object.md)) and forward all parameters to the function in this `axes` object. If the first parameter is an `axes_handle`, the template function will forward all parameters, but the first one, to this `axes` object. This use of templates for the free-standing functions keeps both coding styles maintainable by the developers.
+Both examples would generate the same plot. All free-standing functions are templated functions that use meta-programming to call the main function on the current `axes` object. If the first parameter is not an `axes_handle`, it will get an `axes_handle` from the figure registry with `gca` (Section [Axes Object]()) and forward all parameters to the function in this `axes` object. If the first parameter is an `axes_handle`, the template function will forward all parameters, but the first one, to this `axes` object. This use of templates for the free-standing functions keeps both coding styles maintainable by the developers.
 
 Note that, because the example needs the `axes` object for the function `my_function`, we also need to get a reference to the `axes` object with the free-standing functions. In that case, the free-standing functions are not less verbose than the object-oriented interface.
 
 To adhere to free-standing functions, we could create two versions of `my_function`: one that receives an `axes_handle`, and a second version that would get an `axes_handle` from the figure registry and call the first version. If `my_function` is going to be exposed to other users as a library, this could be a convenience to these users. However, notice that this is only moving the verbosity from the main function to `my_function`. In fact, this is how the free-standing functions in **Matplot++** work.
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/coding-styles/method-chaining.md

@@ -30,3 +30,6 @@ The first code snippet works because `plot` returns a `line_handle` to the objec
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/coding-styles/ranges.md

@@ -29,3 +29,6 @@ Unfortunately, because of how templated functions work, one exception is initial
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/coding-styles/reactive-figures.md

@@ -11,7 +11,7 @@ has_toc: false
 There are also two modes for figures: reactive (or interactive) mode and quiet mode. Figures in reactive mode are updated whenever any of their child objects change. This happens through the `touch` function, that gets called on any child object when it changes its appearance. This creates an interactive mode in which figures are updated as soon as we adjust their properties. If we combine interactive figures with free-standing functions, we have a "Matlab-like style" for plots. This is a coding pattern where the figure registry works as a stream for plots.
 The problem with this coding style is that the user might unnecessarily create useless intermediary plots.
 
-Figures in quiet mode are updated by calling the functions `draw()` or `show()` (Section [Reactive Figures](reactive-figures.md)). Unless these functions are called, nothing changes in the figure. The combination of the object-oriented coding style and quiet mode is the "OO-Matplotlib-like style" for plots. This is a coding style in which the user explicitly decides when the plot is shown or updated. This is beneficial to applications that cannot waste computational resources on intermediary figures that might not be valuable to the application.
+Figures in quiet mode are updated by calling the functions `draw()` or `show()` (Section [Reactive Figures]()). Unless these functions are called, nothing changes in the figure. The combination of the object-oriented coding style and quiet mode is the "OO-Matplotlib-like style" for plots. This is a coding style in which the user explicitly decides when the plot is shown or updated. This is beneficial to applications that cannot waste computational resources on intermediary figures that might not be valuable to the application.
 
 We generally use free-standing functions with reactive mode and the object-oriented interface with quiet mode. By default, new figures are in reactive mode, unless it is using an non-interactive backend. One can turn this reactive mode on and off with:
 
@@ -24,25 +24,28 @@ A more complete example of the reactive mode would be:
 
 ```cpp
 // Reactive mode
-auto f = gcf(false);
+auto f = figure(false);
 auto ax = f->gca();
 auto p = ax->plot(ax, x, y);   // draws once
 p->color("red").line_width(2); // draws twice more
-wait();                        // pause console
+show();                        // pause console
 ```
 
-For convenience, the examples in Section [Examples](../examples.md) use the reactive mode. The `wait` function pauses the console until the user interacts with the plot window. If the backend is based on process pipes, because these are unidirectional, closing the window is not enough to resume. The user needs to use the console to unblock execution. A similar example is quiet mode would be
+For convenience, the examples in Section [Examples]() use the reactive mode. The `show` function pauses the console until the user interacts with the plot window. If the backend is based on process pipes, because these are unidirectional, closing the window is not enough to resume. The user needs to use the console to unblock execution. A similar example is quiet mode would be
 
 ```cpp
 // Quiet mode
-auto f = gcf(true);
+auto f = figure(true);
 auto ax = f->gca();
 auto p = ax->plot(x,y);        // does not draw
 p->color("red").line_width(2); // does not draw
 f->show();                     // draw only once and pause console
 ```
 
-In this example, the figure is only updated once. The user could replace the `show` function with the `draw` function, but the window would close as soon as execution completes. It is important to use `wait()` and `show()` with caution. These functions are meant for some particular executables so that an interactive plot does not close before the user can see it. It is probably unreasonable to call these functions inside a library because the user would have to manually interfere with the execution to continue.
+In this example, the figure is only updated once. The user could replace the `show` function with the `draw` function, but the window would close as soon as execution completes. It is important to use `show()` with caution. These functions are meant for some particular executables so that an interactive plot does not close before the user can see it. It is probably unreasonable to call these functions inside a library because the user would have to manually interfere with the execution to continue.
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/contributing.md

@@ -10,8 +10,8 @@ has_toc: false
 There are many ways in which you can contribute to this library:
 
 * Testing the library in new environments <sup>see [1](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22cross-platform+issue+-+windows%22), [2](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22cross-platform+issue+-+linux%22), [3](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22cross-platform+issue+-+macos%22) </sup>
-* Contributing with interesting examples <sup>see [1](../source/examples)</sup>
-* Designing new backends <sup>see [1](../source/matplot/backend/backend_interface.h), [2](../test/backends/ogl_main.cpp), [3](integration/backends.md), [4](README.md#backends)</sup>
+* Contributing with interesting examples <sup>see [1](https://github.com/alandefreitas/matplotplusplus/blob/master/source/examples)</sup>
+* Designing new backends <sup>see [1](https://github.com/alandefreitas/matplotplusplus/blob/master/source/matplot/backend/backend_interface.h), [2](https://github.com/alandefreitas/matplotplusplus/blob/master/test/backends/ogl_main.cpp), [3](), [4](docs/README.md#backends)</sup>
 * Finding problems in this documentation <sup>see [1](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22enhancement+-+documentation%22) </sup>
 * Writing algorithms for new plot categories <sup>see [1](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22enhancement+-+plot+categories%22) </sup>
 * Finding bugs in general <sup>see [1](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+-+compilation+error%22), [2](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+-+compilation+warning%22), [3](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+-+runtime+error%22), [4](https://github.com/alandefreitas/matplotplusplus/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug+-+runtime+warning%22) </sup>
@@ -29,3 +29,6 @@ Example: CLion
 
 
 - [Contributors](contributing/contributors.md)
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/contributing/contributors.md

@@ -58,3 +58,6 @@ has_toc: false
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples.md

@@ -131,3 +131,6 @@ The examples assume we are in the `matplot` namespace. Use these examples to und
 - [Exporting](examples/exporting.md)
   - [Saving (Manually)](examples/exporting/saving-manually.md)
   - [Saving (Programatically)](examples/exporting/saving-programatically.md)
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations.md

@@ -8,7 +8,7 @@ has_toc: false
 ---
 # Annotations
 
-[Text](annotations/text.md) | [Text with Arrow](annotations/text-with-arrow.md) | [Rectangle](annotations/rectangle.md) | [Filled Polygon](annotations/filled-polygon.md) | [Ellipse](annotations/ellipse.md) | [Textbox](annotations/textbox.md) | [Arrow](annotations/arrow.md) | [Line](annotations/line.md)
+[Text]() | [Text with Arrow](#text-with-arrow) | [Rectangle]() | [Filled Polygon](#filled-polygon) | [Ellipse]() | [Textbox](#textbox) | [Arrow]() | [Line](#line)
 
 The annotations category is meant to create individual objects on the plot rather than representations of data sets. An important difference between the annotations category and other categories is that, by default, the annotations do not replace the plot that already exists in the `axes` object, even if the user does not call the `hold` function.
 
@@ -22,3 +22,6 @@ The annotations category is meant to create individual objects on the plot rathe
 - [Textbox](annotations/textbox.md)
 - [Arrow](annotations/arrow.md)
 - [Line](annotations/line.md)
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations/arrow.md

@@ -25,3 +25,6 @@ More examples:
   
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations/ellipse.md

@@ -22,3 +22,6 @@ See result
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations/filled-polygon.md

@@ -22,3 +22,6 @@ See result
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations/line.md

@@ -22,3 +22,6 @@ See result
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations/rectangle.md

@@ -27,3 +27,6 @@ The rectangle object can have a border curvature from $0$ to $1$. We can also an
   
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations/text-with-arrow.md

@@ -25,3 +25,6 @@ More examples:
   
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations/text.md

@@ -25,3 +25,6 @@ More examples:
   
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->

docs/examples/annotations/textbox.md

@@ -22,3 +22,6 @@ See result
 
 
 
+
+
+<!-- Generated with mdsplit: https://github.com/alandefreitas/mdsplit -->