Adding prototype of the new Faust documentation/manual

documentation/faust-manual/README.md

@@ -0,0 +1,28 @@
+# New Faust Manual / Documentation
+
+This folder contains the prototype of the future Faust documentation/manual.
+It is currently all written in markdown in `faustManual.html`. Running
+`build` will convert this file into the corresponding html page: `index.html`.
+It will automatically add the header, navbar, footer, etc. of the future
+Faust website. If you wish to generate a standalone html doc. You comment the
+last line of the `build` script and un-comment the following one.
+
+## Standards
+
+### Latex Math
+
+Latex Math can be used in Markdown and will be interpreted accordingly (see
+`faustManual.md` for examples).
+
+
+### Runnable Faust Code
+
+Any runnable Faust code can be surrounded the `<!-- faust-run -->` and 
+`<!-- /faust-run -->` tags (see `faustManual.md` for examples).
+
+## Compiling the Old Rail Figures
+
+All the rail figures from the old faust-quick-reference are placed in individual
+files that can be found in `img/src`. Running `pdflatex` will place the
+corresponding figure in an individual pdf file. Pdf files were then converted
+to `svg` using Inkscape and placed in `img`.

documentation/faust-manual/build

@@ -0,0 +1,47 @@
+#!/bin/sh
+
+# Generating html version of markdown
+PHTML=$(pandoc --standalone --toc --toc-depth=4 --metadata pagetitle="Faust Manual" --mathjax faustManual.md)
+
+# Detecting line of end of header added by pandoc
+LINECUT=$(echo "$PHTML" | awk '/<ul>/{ print NR; exit }')
+
+# Getting rid of pandoc header
+PHTML=$(echo "$PHTML" | tail -n +$LINECUT | head -n -2)
+
+# Adding elements for CSS, etc.
+PHTML=$(echo "<div class=\"container-fluid\"><div class=\"row faust-doc\"><nav id=\"TOC\" class=\"col-3 faust-doc-content\"><div style=\"height: 100%;overflow-y: scroll;\"><ul class=\"nav flex-column\">$PHTML")
+PHTML=$(echo "$PHTML" | awk '/<h1 id=\"faust-manual\">/{print "<main role=\"main\" class=\"col-9 ml-sm-auto px-4 faust-doc-content\">\n<div data-spy=\"scroll\" data-target=\"#TOC\" data-offset=\"0\" style=\"height: 100%;overflow-y: scroll;\">"}1' | awk '/<\/nav>/{print "</div>"}1')
+
+# Extracting Faust files to be sent to the editor and generating correspind diags
+EXFAUSTDIR="img/src/exfaust"
+FAUSTCODES=$(echo "$PHTML" | awk '/<!-- faust-run -->/,/<!-- \/faust-run -->/')
+CNT=0
+while [ ! -z "$FAUSTCODES" ]
+do
+  CURRENT_FAUST_FILE="$EXFAUSTDIR$CNT/exfaust$CNT.dsp"
+  # Removing existing dir, in case...
+  rm -rf $EXFAUSTDIR$CNT 
+  # Creating dir for code and SVG
+  mkdir $EXFAUSTDIR$CNT
+  # Formating code from file
+  # TODO: files could be trimed to get rid of empty line at beginning and end
+  echo "$FAUSTCODES" | awk '1;/<!-- \/faust-run -->/{exit}' | awk '{gsub(/<!-- faust-run -->/,"")}1' | awk '{gsub(/<!-- \/faust-run -->/,"")}1' | awk '{gsub(/<pre><code>/,"")}1' | awk '{gsub(/<\/code><\/pre>/,"")}1' | awk '{gsub(/&quot;/,"\"")}1' > $CURRENT_FAUST_FILE
+  # Generating SVG
+  faust2svg $CURRENT_FAUST_FILE
+  # Cleaning current example
+  CODE_LENGTH=$(cat $CURRENT_FAUST_FILE | wc -l)
+  FAUSTCODES=$(echo "$FAUSTCODES" | tail -n +$((CODE_LENGTH+1)))
+  # Formating Faust runnable examples in html
+  FAUST_HEADER="<div class=\"faust-run\"><a href=\"$EXFAUSTDIR$CNT/exfaust$CNT-svg/process.svg\" target=\"_blank\"><img src=\"$EXFAUSTDIR$CNT/exfaust$CNT-svg/process.svg\" class=\"mx-auto d-block\"></a>"
+  PHTML=$(echo "$PHTML" | awk -v var="$FAUST_HEADER" '/<!-- faust-run -->/ && n==0 {sub(/<!-- faust-run -->/,var);++n}{print}')
+  FAUST_FOOTER="<a href=\"http://faust.grame.fr/editor?code=$CURRENT_FAUST_FILE\"><button type=\"button\" class=\"btn btn-primary\">Try it Yourself >></button></a></div>"
+  PHTML=$(echo "$PHTML" | awk -v var="$FAUST_FOOTER" '/<!-- \/faust-run -->/ && n==0 {sub(/<!-- \/faust-run -->/,var);++n}{print}')
+  # Going to next code...
+  ((CNT++))
+done
+
+# Add the header and the footer of the future Faust website
+echo "$PHTML</div></div></div></main>" | cat lib/header-faust.html - lib/footer.html > index.html
+# Add the header and the footer to make a standalone HTML page
+#echo "$PHTML</div></div></div></main>" | cat lib/header-doc.html - lib/footer.html > index.html

documentation/faust-manual/css/faust-doc.css

@@ -0,0 +1,25 @@
+.faust-doc {
+  height: 100vh;
+}
+
+.faust-doc-content {
+  padding-top:0rem;
+  padding-right:0rem!important;
+}
+
+ul {
+  padding-left: 1rem;
+}
+
+/* TODO: not sure why this needs to be done */
+pre {
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  background-color: #f5f5f5;
+  padding: 0.5rem;
+}
+
+#TOC {
+  background-color: #f5f5f5;
+}
+

documentation/faust-manual/css/faust-website.css

@@ -0,0 +1,69 @@
+.navbar-brand{
+  margin-right: 3rem;
+  font-weight: bold;
+  font-size: 1.5rem;
+}
+
+/* Carousel base class */
+.carousel {
+  margin-bottom: 4rem;
+}
+/* Since positioning the image, we need to help out the caption */
+.carousel-caption {
+  bottom: 3rem;
+  z-index: 10;
+}
+
+/* Declare heights because of positioning of img element */
+.carousel-item {
+  height: 32rem;
+  background-color: #777;
+}
+.carousel-item > img {
+  position: absolute;
+  top: 0;
+  left: 0;
+  min-width: 100%;
+  height: 32rem;
+}
+
+.footer {
+  bottom: 0;
+  width: 100%;
+  background-color: #f5f5f5;
+}
+
+.footer-content{
+  padding-top: 2rem;
+  padding-bottom: 2rem;
+}
+
+.copyright{
+  text-align: center;
+}
+
+.faust-doc {
+  height: 100vh;
+}
+
+.faust-doc-content {
+  padding-top:8rem;
+  padding-right:0rem!important;
+}
+
+ul {
+  padding-left: 1rem;
+}
+
+/* TODO: not sure why this needs to be done */
+pre {
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  background-color: #f5f5f5;
+  padding: 0.5rem;
+}
+
+#TOC {
+  background-color: #f5f5f5;
+}
+

documentation/faust-manual/css/faust-widget.css

@@ -0,0 +1,15 @@
+.faust-run {
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  padding: 0.5rem;
+  background-color: #f5f5f5;
+}
+
+.faust-run img {
+  padding: 0.5rem;
+}
+
+.faust-run pre {
+  background-color: white; 
+}
+

documentation/faust-manual/faustManual.md

@@ -0,0 +1,154 @@
+# Faust Manual
+
+This is code: `process = -;`.
+
+```
+process = +;
+```
+
+And here's a working Faust example:
+
+<!-- faust-run -->
+```
+import("stdfaust.lib");
+freq = hslider("freq",440,50,2000,0.01);
+process = os.osc(freq);
+```
+<!-- /faust-run -->
+
+and another one:
+
+<!-- faust-run -->
+```
+import("stdfaust.lib");
+freq = hslider("freq",440,50,2000,0.01);
+process = os.sawtooth(freq);
+```
+<!-- /faust-run -->
+
+More precisely :
+
+* A *signal* $s$ is a discrete function of time $s:\mathbb{Z}\rightarrow\mathbb{R}$.
+
+# Faust Syntax
+
+## Expressions
+
+Despite its textual syntax, Faust is conceptually a block-diagram language. 
+Faust expressions represent DSP block-diagrams and are assembled from primitive 
+ones using various *composition* operations. More traditional *numerical* 
+expressions in infix notation are also possible. Additionally Faust provides 
+time based expressions, like delays, expressions related to lexical 
+environments, expressions to interface with foreign function and lambda 
+expressions.
+
+<img src="img/expression.svg" class="mx-auto d-block">
+
+### Diagram Expressions
+
+Diagram expressions are assembled from primitive ones using either binary composition operations or high level iterative constructions.
+
+<img src="img/diagramexp.svg" class="mx-auto d-block">
+
+#### Diagram Composition Operations 
+
+Five binary *composition operations* are available to combine block-diagrams: 
+
+* *recursion* (`~`),
+* *parallel* (`,`),
+* *sequential* (`:`),
+* *split* (`<:`),
+* *merge* (`:>`).
+
+One can think of each of these composition operations as a particular way to 
+connect two block diagrams. 
+
+<img src="img/diagcomposition.svg" class="mx-auto d-block">
+
+To describe precisely how these connections are done, we have to introduce some 
+notation. The number of inputs and outputs of a block-diagram $A$ are expressed 
+as $\mathrm{inputs}(A)$ and $\mathrm{outputs}(A)$. The inputs and outputs 
+themselves are respectively expressed as: $[0]A$, $[1]A$, $[2]A$, $\ldots$ and 
+$A[0]$, $A[1]$, $A[2]$, etc. 
+
+For each composition operation between two block-diagrams $A$ and $B$ we will 
+describe the connections $A[i]\rightarrow [j]B$ that are created and the 
+constraints on their relative numbers of inputs and outputs.
+
+The priority and associativity of this five operations are.
+
+#### Parallel Composition
+
+#### Sequential Composition
+
+#### Split Composition
+
+#### Merge Composition
+
+#### Recursive Composition
+
+#### Inputs and Outputs of an Expression
+
+#### Iterations 
+
+### Infix Notation and Other Syntax Extensions
+
+#### Math Operators
+
+#### Bitwise Operators
+
+#### Comparison
+
+#### Delay
+
+#### Prefix Notation
+
+#### Partial Application
+
+### Time Expressions
+
+#### `@` Operator
+
+#### `'` Operator 
+
+### Environment Expressions
+
+#### `with`
+
+#### `letrec`
+
+#### `environment`
+
+#### Access
+
+#### `library`
+
+<!-- TODO: import? -->
+
+#### `component`
+
+#### Explicit Substitution
+
+### Foreign Expressions
+
+#### `ffunction`
+
+#### Signature
+
+#### Types
+
+#### Variables and Constants
+
+#### File Include
+
+#### Library File
+
+### Applications and Abstractions
+
+#### Abstractions 
+
+#### Applications
+
+#### Pattern Matching
+
+## Primitives