format documentation

doc/sources/README.md

@@ -1,10 +1,13 @@
 # Introduction
 
-Sniprun is a code runner plugin for neovim written in Lua and Rust. It aims to provide stupidly fast partial code testing for interpreted **and compiled** {ref}`languages <support-levels-and-languages>`. Sniprun blurs the line between standard save/run workflow, jupyter-like notebook, and REPL/interpreters.
+Sniprun is a code runner plugin for neovim written in Lua and Rust. It aims to
+provide stupidly fast partial code testing for interpreted **and compiled**
+{ref}`languages <support-levels-and-languages>`. Sniprun blurs the line
+between standard save/run workflow, jupyter-like notebooks,
+and REPL/interpreters.
 
-
-
-I know that this README is exhaustively long, but Sniprun itself is and will remain rather simple: don't be afraid, questions are welcome too.
+I know that this README is exhaustively long, but Sniprun itself is and will
+remain rather simple: don't be afraid, questions are welcome too.
 
 ## Demos
 
@@ -13,7 +16,7 @@ A few lines of code are now within a print statement's reach :-) ([this may be c
 
 An example in C, look in the command area:
 
-![](../../ressources/visual_assets/demo_c.gif)
+![demo_c](../../ressources/visual_assets/demo_c.gif)
 
 **The result can be returned in multiple (even at the same time) ways:**
 
@@ -28,11 +31,12 @@ An example in C, look in the command area:
 
 **send-to-REPL-like behavior is available for some languages**
 
-Python, R, D, Mathematica, Sage, Julia, Javascript & Typescript (via deno), Clojure and Lua, coming soon for many other interpreted and compiled languages. Very versatile, you can even run things like GUI plots on the fly!
+Python, R, D, Mathematica, Sage, Julia, Javascript & Typescript (via deno),
+Clojure and Lua, coming soon for many other interpreted and compiled languages.
+Very versatile, you can even run things like GUI plots on the fly!
 
 ![](../../ressources/visual_assets/demo_repl.png)
 
-
 # What does it do ?
 
 Basically, it allows you to run a part of your code.
@@ -48,7 +52,6 @@ Do either of:
 
 and ... that's it!
 
-
 Sniprun will then:
 
 - **Get the code** you selected (selections are rounded line-wise)
@@ -58,9 +61,6 @@ Sniprun will then:
 - **Execute** the code, or send it to an active REPL for evaluation
 - Display stdout, or stderr using the chosen method
 
-
-
-
 # What it is && isn't
 
 **It is** a way to quickly run small snippets of code, on the fly, and iterate very quickly and conveniently. To quickly experiment with new features (not yet embedded in classes, a whole project etc...), or to develop simple code pipelines (like a machine learning exercise) that fit in a unique file, sniprun is probably _the_ best plugin out there.

doc/sources/interpreters/Ada_original.md

@@ -1,11 +1,12 @@
 ## Ada original
 
-
 dependencies: Need `gcc-ada` and `gnatmake`
 
 
-Note: because Ada needs variables to be declared before the begin (in a non contiguous section of the file), SnipRun is not very useful here and will, in practice, only be able to run blocs like
+Note: because Ada needs variables to be declared before the begin
+(in a non contiguous section of the file), SnipRun is not very useful
+here and will, in practice, only be able to run blocs like
 
-```
+```ada
 Put_Line("raw text");
 ```

doc/sources/interpreters/Bash_original.md

@@ -1,7 +1,9 @@
 ## Bash original
 
-Beware of Bash_original, as it runs as script on your system, with access to your ENV variables and PATH etc...
+Beware of Bash_original, as it runs as script on your system,
+with access to your ENV variables and PATH etc...
 
-remove a file from absolute path will succeed!
+removing a file from absolute path will succeed!
 
-REPL mode has also many quirks (not a true repl, will rerun previously sniprun'd commands). Overall I strongly suggest _not_ using it
+REPL mode has also many quirks (not a true repl, will rerun
+previously sniprun'd commands). Overall I strongly suggest _not_ using it

doc/sources/interpreters/CSharp_original.md

@@ -1,6 +1,7 @@
 ## C# original
 
-This interpreter require the `mono` toolbox to be installed: `csc` and `mono` must be in your $PATH
+This interpreter require the `mono` toolbox to be installed:
+`csc` and `mono` must be in your $PATH
 
 a custom compiler can be specified :
 
@@ -14,5 +15,3 @@ require'sniprun'.setup({
     }
 })
 ```
-
-

doc/sources/interpreters/C_original.md

@@ -1,7 +1,7 @@
 ## C original
 
-`gcc` is recommended, for that it's able to detect, compile and run nested functions, however you can change the default compiler with:
-
+`gcc` is recommended, for that it's able to detect, compile and run nested
+functions, however you can change the default compiler with:
 
 ```lua
 require'sniprun'.setup({
@@ -14,9 +14,15 @@ require'sniprun'.setup({
 })
 ```
 
-If you run with GCC, Sniprun will be able to run function + code in the same snippet, or functions + main() function regardlessly, but only the latter is supported by `clang`.
+If you run with GCC, Sniprun will be able to run function + code in the
+same snippet, or functions + main() function regardlessly, but only the
+latter is supported by `clang`.
 
-This interpreter will also only import (all)  #include \<...> but not any #include "..." (systems-wide include only, not the headers from your project, unless the environment variable `$C_INCLUDE_PATH` or `$CPLUS_INCLUDE_PATH` have been set). In this case, please make sure those variable cover **ALL** the paths needed to fetch every header file `#include`'d
+This interpreter will also only import (all)  #include \<...> but not
+any #include "..." (systems-wide include only, not the headers from your
+project, unless the environment variable `$C_INCLUDE_PATH` or
+`$CPLUS_INCLUDE_PATH` have been set). In this case, please make sure those
+variable cover **ALL** the paths needed to fetch every header file `#include`'d
 
 
 the C\_original interpreter will also make use of the following environment variables:
@@ -27,7 +33,9 @@ the C\_original interpreter will also make use of the following environment vari
 - `$CFLAGS`
 
 
-and will add them to the build options it uses. Please specify _absolute paths_, and not relative ones!
+and will add them to the build options it uses.
+Please specify _absolute paths_, and not relative ones!
 
 
-Using a tool such as [direnv](https://direnv.net/) may be really useful to set up those variables when you `cd` into your project' directory.
+Using a tool such as [direnv](https://direnv.net/) may be really useful
+to set up those variables when you `cd` into your project' directory.

doc/sources/interpreters/Clojure_fifo.md

@@ -2,9 +2,9 @@
 
 This interpreter relies on `clojure`
 
-
-The default interpreter command is `clojure` (or `clojure -e "(clojure.main/repl :prompt (defn f[] ("")) )"`, that allow not displaying the repl prompt) but it can be changed via the configuration key
-
+The default interpreter command is `clojure`
+(or `clojure -e "(clojure.main/repl :prompt (defn f[] ("")) )"`, that allow
+not displaying the repl prompt) but it can be changed via the configuration key
 
  The defaults are equivalent to specifying:
 
@@ -19,12 +19,13 @@ require'sniprun'.setup({
     }
 })
 ```
-You can change those values, (to use `clj` for example ?) but it could break sniprun anytime
-
 
+You can change those values, (to use `clj` for example ?)
+but it could break sniprun anytime
 
 ### Blocked REPL
 
-Clojure is a bit capricious and sometimes a typo will block forever (and a timeout will appear after 30s). 
-
-Don't hesitate to `SnipReset`, even though it will lose all the currently in-memory variables
+Clojure is a bit capricious and sometimes a typo will block forever
+(and a timeout will appear after 30s). 
+Don't hesitate to `SnipReset`, even though it will lose all
+the currently in-memory variables...

doc/sources/interpreters/Cpp_original.md

@@ -2,8 +2,13 @@
 
 Limitations
 
- - Will only look and load external imports (include) that are SYSTEM import; as sniprun does not have any way to differentiate between #include "math.h"  (the system library) and #include "math2.h" (your custom header), it will NOT look for #include "....", but only #include \<....>   (those are restricted to system libraries).
- - Need `g++` (or specify another compiler in configuration)
+- Will only look and load external imports (include) that are SYSTEM import;
+  as sniprun does not have any way to differentiate between #include "math.h"
+  (the system library) and #include "math2.h" (your custom header),
+  it will NOT look for #include "....", but only #include \<....>
+  (those are restricted to system libraries).
+
+- Need `g++` (or specify another compiler in configuration)
 
 ```lua
 require'sniprun'.setup({

doc/sources/interpreters/FSharp_fifo.md

@@ -2,9 +2,8 @@
 
 ### This interpreter relies on dotnet fsi being available and on your path
 
-
-The default interpreter command is `dotnet fsi --nologo` but it can be changed via the configuration key
-
+The default interpreter command is `dotnet fsi --nologo` but it
+can be changed via the configuration key
 
 ```lua
 require'sniprun'.setup({
@@ -17,18 +16,17 @@ require'sniprun'.setup({
 })
 ```
 
-
 ### REPL (would solve slowness issues)
 
 For now, REPL is broken due to dotnet fsi being capricious about its stdin.
 
-I'll explain rapidly how sniprun implement a REPL interpreter around named pipes (FIFOs).
+I'll explain rapidly how sniprun implements a REPL interpreter
+around named pipes (FIFOs).
 
-The first time a fifo-based interpreter receive a run command, it forks to the background and executes `ressources/init_repl.sh`.
+The first time a fifo-based interpreter receive a run command,
+it forks to the background and executes `ressources/init_repl.sh`.
 There is a lot of thing in that script but to replicate, you just have to:
 
-
-
 - `mkfifo pipe_in`
 
 - create a launcher script:
@@ -40,24 +38,29 @@ cat pipe_in | dotnet fsi
 # or replace 'dotnet fsi' by whatever you cant to try
 ```
 
-- launch it in the background: `bash ./launcher.sh &`, (or `bash ./launcher.sh > out.txt & ` to redirect stdout to out.txt like sniprun does)
+- launch it in the background: `bash ./launcher.sh &`,
+  (or `bash ./launcher.sh > out.txt & ` to redirect stdout to out.txt like sniprun does)
 
-- ensure the pipe will stay open: `sleep 3600 > pipe_in &` (cat, exec 3> variations will also work)
+- ensure the pipe will stay open: `sleep 3600 > pipe_in &`
+  (cat, exec 3> variations will also work)
 
 - `echo "printfn \" hey \" " > pipe_in` or `cat hello_world.fsx > pipe_in`
 
-- normally, the result should be printed in the terminal that ran the launcher, or in the out file.
-
-
-
+- normally, the result should be printed in the terminal that ran
+  the launcher, or in the out file.
 
 #### The issue:
 
-right now, dotnet fsi looks like it's blocked by the first sleep > pipe_in... but something **has** to keep the pipe open or when it closes, the fsi REPL reading from that will exit.
+right now, dotnet fsi looks like it's blocked by the first sleep > pipe_in...
+but something **has** to keep the pipe open or when it closes, the fsi REPL
+reading from that will exit.
 
 I suspect the thing has something to do with interactive mode. 
 
-For example, `python` has a similar problem, but `python -i ` (forced interactive mode, even if no terminal is detected because it runs in the background / its stdin was hijacked) works fine in the above example.
+For example, `python` has a similar problem, but `python -i `
+(forced interactive mode, even if no terminal is detected because it
+runs in the background / its stdin was hijacked) works fine in the above example
 
-If you find something to replace dotnet fsi with, that exhibits the same correct behavior as `python -i`, sniprun REPL mode _should_ work.
+If you find something to replace dotnet fsi with, that exhibits the same
+correct behavior as `python -i`, sniprun REPL mode _should_ work.
 

doc/sources/interpreters/GFM_original.md

@@ -4,13 +4,10 @@ the GFM_original (Github flavored markdown) can help run code blocs embedded in
 
 ### example 1
 
-
 \```bash
 
 echo "lol"  # << you can run sniprun on this line
 
-
-
 \# or the whole visual selection following:
 
 for i in {1..4};do
@@ -31,10 +28,11 @@ println!("test");
 
 \``` 
 
+**the language name must be there (otherwise the default * will be used) at the
+bloc start** and has to match the github flavor syntax, and the underlying
+interpreter must be callable (no missing compiler etc...)
 
-**the language name must be there (otherwise the default * will be used) at the bloc start** and has to match the github flavor syntax, and the underlying interpreter must be callable (no missing compiler etc...)
-
-\* python, but you can ofc configure that: 
+\* python, but you can ofc configure that:
 
 ```lua
 require'sniprun'.setup({
@@ -46,9 +44,6 @@ require'sniprun'.setup({
 })
 ```
 
-
-if GFM doesn't include a flavor that matches the language you want, well it's not really GFM anymore but you can but the filetype of the language you want, such as julia or lua
-
-
-
-
+if GFM doesn't include a flavor that matches the language you want, well it's
+not really GFM anymore but you can but the filetype of the language you want,
+such as julia or lua

doc/sources/interpreters/Generic.md

@@ -1,19 +1,19 @@
 ## Generic
 
-This interpreter allows you to support virtually any language, provided it's not too strange, at up to bloc-level
+This interpreter allows you to support virtually any language,
+provided it's not too strange, at up to bloc-level
 
-If you're trying to override an already-supported language, add Generic to the list of selected interpreters:
+If you're trying to override an already-supported language,
+add Generic to the list of selected interpreters:
 
 
 ```lua
 require'sniprun'.setup({
     selected_interpreters = { 'Generic' },
 })
 ```
-
 to add support for, let's say, python2
 
-
 ```lua
 require'sniprun'.setup({
     interpreter_options = {
@@ -34,7 +34,6 @@ require'sniprun'.setup({
 
 to also add support for, let's suppose it wasn't officially supported, C
 
-
 ```lua
 require'sniprun'.setup({
     interpreter_options = {
@@ -84,11 +83,12 @@ require'sniprun'.setup({
 
 1. Sniprun receive a snippet of code to run
 2. The snippet gets surrounded by boilerplate_pre and boilerplate_post
-3. The whole thing is written to a temporary file with the given extension, named `<exe_name>_src.<extension>`
-4. Sniprun runs `<compiler>  <exe_name>_src.<extension>` , and if this has a non-success status, displays the stderr
+3. The whole thing is written to a temporary file with the given extension,
+   named `<exe_name>_src.<extension>`
+4. Sniprun runs `<compiler>  <exe_name>_src.<extension>` , and if this has a
+   non-success status, displays the stderr
 5. Sniprun runs `./<exe_name>` and displays the stdout/stderr
 
-
 ### Community examples for non-officially supported languages
 
-(contribute here: doc/sources/interpreters/Generic.md)
+(contribute on github to the file: doc/sources/interpreters/Generic.md)

doc/sources/interpreters/Go_original.md

@@ -1,5 +1,6 @@
 ## Go original
-the executable (`go` , `llgo` or whatever) executable used to _build_ the snippet can be configured via
+the executable (`go` , `llgo` or whatever) executable used to
+_build_ the snippet can be configured via
 
 
 ```lua
@@ -13,4 +14,3 @@ require'sniprun'.setup({
 })
 ```
 
-

doc/sources/interpreters/Http_original.md

@@ -1,5 +1,6 @@
 ## Http original
 
-This interpreter does not have any requirements, as it relies on the (embedded) Rust library [ureq](https://crates.io/crates/ureq/)
+This interpreter does not have any requirements, as
+it relies on the (embedded) Rust library [ureq](https://crates.io/crates/ureq/)
 
 It works on filetypes 'http' and 'rest'.

doc/sources/interpreters/JS_TS_bun.md

@@ -4,11 +4,11 @@ A REPL-capable (not enabled by default) Typescript / Javascript interpreter.
 
 `bun` needs to be installed and on your path.
 
-
 ### JS_TS_bun is REPL-capable
 
 But the REPL is VERY quirky (and even has a greeting saying it's unstable)
-It doesn't play well at all with sniprun's stdin-stdout mechanism, so while basic examples are working,
+It doesn't play well at all with sniprun's stdin-stdout
+mechanism, so while basic examples are working,
 I can't consider this a 'daily driver'... so REPL is disabled by default
 
 ```lua
@@ -18,7 +18,6 @@ require('sniprun').setup({
 })
 ```
 
-
 ### more option for the (non-repl) command line
 
 sniprun runs your code snippets with