Style suggestions

mkdocs/docs/manual/overview.md

@@ -1,17 +1,17 @@
 # Overview of the Faust Universe
 
-While in its most *primitive* form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grab at first. This chapter provides an overview of their role and will hopefully help you decide which one is better suited for your personal use. 
+In its most *primitive* form, Faust is distributed as a command-line compiler. However, a wide range of additional tools have also been developed for Faust. While the variety and function of these tools might be hard to grasp at first, this chapter aims to provide an overview of each their roles and will hopefully help you decide when you might want to use a given tool.
 
 <!-- TODO: it'd be nice to have some kind of figure here summarizing everything the various Faust branches should appear in this figure: we want something as complete as possible. -->
 
 ## The Faust Distribution
 
-The Faust distribution hosts the source of the Faust compiler (both in its command line and library version), the source of the Faust *architectures* (targets), the various Faust compilation scripts, a wide range of Faust-related-tools, the [Faust DSP Libraries](https://faustlibraries.grame.fr) (which in practice are hosted a separate Git submodule), etc.
+The Faust distribution hosts the source of the Faust compiler (both in its command line and library version), the source of the Faust *architectures* (targets), the various Faust compilation scripts, a wide range of Faust-related-tools, the [Faust DSP Libraries](https://faustlibraries.grame.fr) (which in practice are hosted in a separate Git submodule), and more.
 
-The latest stable release of the Faust distribution can be found [here](https://github.com/grame-cncm/faust/releases). It is recommended for most Faust users willing to compile the Faust compiler and libfaust from scratch.
+The latest stable release of the Faust distribution can be found [here](https://github.com/grame-cncm/faust/releases). It is recommended for Faust users who are willing to compile the Faust compiler and libfaust from scratch.
 
-To have the latest stable development version, you can use the `master branch` of the Faust [git repository](https://github.com/grame-cncm/faust/tree/master) which is hosted on GitHub. For something even more bleeding edge (to be used at your own risk), you can use the `master-dev` branch of the Faust [git repository](https://github.com/grame-cncm/faust/tree/master-dev). 
-`master-dev` is the development sub-branch of `master`. It is used by Faust developers to commit  their changes and can be considered as "the main development branch". The goal is to make sure that `master` is always functional. Merges between `master-dev`  and `master` are carried out at each stable release by the GRAME team.
+To get the latest stable development version, you can use the `master branch` of the Faust [git repository](https://github.com/grame-cncm/faust/tree/master), which is hosted on GitHub. For something even more bleeding edge (to be used at your own risk), you can use the `master-dev` branch of the Faust [git repository](https://github.com/grame-cncm/faust/tree/master-dev).
+`master-dev` is the development sub-branch of `master`. It is used by Faust developers to commit their changes and can be considered the "main development branch". The goal is to make sure that `master` is always functional. Merges between `master-dev` and `master` are carried out at each stable release by the GRAME team.
 
 Also, note that pre-compiled packages of the Faust compiler and of libfaust for various platforms can be found on the of the [Faust website](https://faust.grame.fr).
 
@@ -24,7 +24,7 @@ share/         : contains documentation, the Faust libraries and architecture fi
 
 **Note**: you can install the Faust distribution anywhere you want, provided that the `faust` command is available from your PATH (this requires updating your .profile if it's not in a standard location). 
 
-The following subsections present the main tools built on top of the Faust compiler and intended to facilitate your life. 
+The following subsections present the main tools built on top of the Faust compiler that should make your life easier (while coding with Faust at least).
 
 ## Faust IDE
 
@@ -36,7 +36,7 @@ The following subsections present the main tools built on top of the Faust compi
 
 ## Faust Playground
 
-[Faust Playground](https://faustplayground.grame.fr) is a graphical environment to develop Faust programs with a higher level approach. It has been initially designed for kids and for pedagogical purpose.
+[Faust Playground](https://faustplayground.grame.fr) is a graphical environment to develop Faust programs with a higher level approach. It was designed for kids and for pedagogical purposes.
 
 ## Faustgen
 
@@ -46,4 +46,4 @@ Faustgen is a Max/MSP external that provides features similar to FaustLive. It's
 
 [FaustLive](https://github.com/grame-cncm/faustlive) is an advanced self-contained prototyping environment for the Faust programming language with an ultra-short edit-compile-run cycle. Thanks to its fully embedded compilation chain, FaustLive is simple [to install](https://github.com/grame-cncm/faustlive/releases) and doesn't require any external compiler, development toolchain or SDK to run.
 
-FaustLive is the ideal tool for fast prototyping. Faust programs can be compiled and run on the fly by simple drag and drop. They can even be edited and recompiled while running, without sound interruption. It also supports native application generation using the Faust online compiler. **Note that FaustLive is regularly recompiled, but is no longer developed, so Faust IDE is the recommended tool to use**.  
+FaustLive is the ideal tool for fast prototyping. Faust programs can be compiled and run on the fly with just a simple drag and drop. Programs can even be edited and recompiled while running, without sound interruption. FaustLive also supports native application generation using the Faust online compiler. **Note that FaustLive is regularly recompiled, but is no longer developed. It is recommended to use Faust IDE instead**.  

src/manual/introduction.md

@@ -14,6 +14,8 @@ This manual gives an overview of the Faust programming language and of its featu
 
 ## What is Faust Good For?
 
+### Block Diagrams
+
 Faust's syntax allows us to express any DSP algorithm as a block diagram. For example, `+` is considered as a valid function (and block) taking two arguments (signals) and returning one:
 
 <!-- faust-run -->
@@ -34,6 +36,8 @@ In that case, we add two signals together and then scale the result of this oper
 
 Thus, **Faust is perfect to implement time-domain algorithms that can be easily represented as block diagrams** such as filters, waveguide physical models, virtual analog elements, etc.
 
+### Concise Code
+
 **Faust is very concise**, for example, here's the implementation of a one pole filter/integrator equivalent to \(y(n) = x(n) + a_{1}y(n-1)\) (where \(a_{1}\) is the pole):
 
 <!-- faust-run -->
@@ -43,7 +47,11 @@ process = +~*(a1);
 ```
 <!-- /faust-run -->
 
-**Code generated by Faust are extremely optimized** and usually more efficient than handwritten code (at least for C and C++). The Faust compiler tries to optimize each element of an algorithm. For example, you shouldn't have to worry about using divides instead of multiplies as they get automatically replaced by multiplies by the compiler when possible, etc.
+### Optimized
+
+**Code generated by Faust is extremely optimized** and is usually more efficient than handwritten code (at least for C and C++). The Faust compiler tries to optimize each element of an algorithm. For example, you shouldn't have to worry about using division instead of multiplication in Faust code as the compiler automatically replaces division with multiplication in the compiled output whenever possible.
+
+### Cross-platform
 
 **Faust is very generic** and allows us to write code that will run on dozens of platforms.
 
@@ -54,7 +62,7 @@ other words be a bit more specific here. -->
 
 Despite all this, Faust does have some limitations. For instance, it doesn't allow for the efficient implementation of algorithms requiring multi-rates such as the FFT, convolution, etc. While there are tricks to go around this issue, we're fully aware that it is a big one and we're working as hard as possible on it.
 
-Faust's conciseness can sometimes become a problem too, especially for complex algorithms with lots of recursive signals. It is usually crucial in Faust to have the "mental global picture" of the algorithm to be implemented which in some cases can be hard.
+Faust's conciseness can be a problem as well, especially for complex algorithms with lots of recursive signals. It is usually crucial in Faust to have a "mental global picture" of the algorithm you are implementing which can be difficult.
 
 While the Faust compiler is relatively bug-free, it does have some limitations and might get stuck in some extreme cases that you will probably never encounter. If you do, [shoot us an e-mail](mailto:[email protected])!
 
@@ -64,17 +72,16 @@ From here, you can jump to the [Quick Start Tutorial](quick-start.md) section of
 
 Since the beginning of its development in 2002, Faust has been guided by various design principles:
 
-* Faust is a *specification language*. It aims at providing an adequate notation to describe *signal processors* from a mathematical point of view. Faust is, as much as possible, free from implementation details. 
-* Faust programs are fully compiled (i.e., not interpreted). The compiler translates Faust programs into equivalent programs in other languages (e.g., JAVA, LLVM IR, WebAssembly, etc.) taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers. 
-* The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint. 
-* The semantics of Faust is simple and well defined. This is not just of academic interest. It allows the Faust compiler to be *semantically driven*. Instead of compiling a program literally, it compiles the mathematical function it denotes. This feature is useful for example to promote components reuse while preserving optimal performance.  
-* Faust is a textual language but nevertheless block-diagram oriented. It actually combines two approaches: *functional programming* and *algebraic block-diagrams*. The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a *block-diagram algebra* of five composition operations: `: , ~ <: :>` (see the section on [Diagram Composition Operations](syntax.md#diagram-composition-operations) for more details).
+* Faust is a *specification language*. It aims at providing an adequate notation to describe *signal processors* from a mathematical point of view. Faust is, as much as possible, free from implementation details.
+* Faust programs are fully compiled (i.e., not interpreted). The compiler translates Faust programs into equivalent programs in other languages (e.g., JAVA, LLVM IR, WebAssembly, etc.) taking care of generating the most efficient code. The result can generally compete with, and sometimes even outperform, C++ code written by seasoned programmers.
+* The generated code works at the sample level. It is therefore suited to implement low-level DSP functions like recursive filters. Moreover the code can be easily embedded. It is self-contained and doesn't depend of any DSP library or runtime system. It has a very deterministic behavior and a constant memory footprint.
+* The semantics of Faust are simple and well defined. This is not just of academic interest. It allows the Faust compiler to be *semantically driven*. Instead of compiling a program literally, it compiles the mathematical function it denotes. One reason this is useful is that it helps promote component reuse while preserving optimal performance.
+* Faust is a textual language (i.e. written with text) but is also block-diagram oriented. It combines two approaches: *functional programming* and *algebraic block-diagrams*. The key idea is to view block-diagram construction as function composition. For that purpose, Faust relies on a *block-diagram algebra* of five composition operations: `:`, `,`, `~`, `<:` and `:>` (see the section on [Diagram Composition Operations](syntax.md#diagram-composition-operations) for more details).
 * Thanks to the concept of *architecture*, Faust programs can be easily deployed on a large variety of audio platforms and plug-in formats without any change to the Faust code.
 
 ## Signal Processor Semantics
 
-A Faust program describes a *signal processor*. The role of a *signal processor* is to transforms a (possibly empty) group of *input signals* in order to produce a (possibly empty) group of *output signals*. Most audio equipment can be modeled as *signal processors*. They have audio inputs, audio outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. 
-
+A Faust program describes a *signal processor*. The role of a *signal processor* is to transform a (possibly empty) group of *input signals* and use the result to produce a (possibly empty) group of *output signals*. Most audio equipment can be modeled as *signal processors*. They have audio inputs and outputs as well as control signals interfaced with sliders, knobs, vu-meters, etc. 
 More precisely :
 
 * A *signal* \(s\) is a discrete function of time \(s:\mathbb{Z}\rightarrow\mathbb{R}\). The value of a signal \(s\) at time \(t\) is written \(s(t)\). The values of signals are usually needed starting from time \(0\). But to take into account *delay operations*, negative times are possible and are always mapped to zeros. Therefore for any Faust signal \(s\) we have \(\forall t<0, s(t)=0\). In operational terms this corresponds to assuming that all delay lines are signals initialized with \(0\)s. 

src/manual/tools.md

@@ -1,6 +1,6 @@
 # `faust2[...]` Tools
 
-While in its most *primitive* form, Faust is distributed as a command-line compiler, a wide range of tools have been developed around it in the course of the past few years. Their variety and their function might be hard to grasp at first. This description provides an overview of their role and will hopefully help you decide which one is better suited for your personal use. 
+In its most *primitive* form, Faust is distributed as a command-line compiler. However, a wide range of additional tools have also been developed for Faust. While the variety and function of these tools might be hard to grasp at first, this section aims to provide an overview of each their roles and will hopefully help you decide when you might want to use a given tool.
 
 The Faust tools is a set of scripts that take a dsp file as input to generate various output for a lot of architectures and platforms. All the tools names are in the form `faust2xx` where `xx` is the target architecture.