Complete FAQ.

docs/index.html

@@ -473,5 +473,5 @@ <h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
 
 <!--
 MkDocs version : 1.5.3
-Build Date UTC : 2025-01-01 21:05:43.401281+00:00
+Build Date UTC : 2025-01-02 10:21:00.146429+00:00
 -->

docs/manual/errors/index.html

@@ -395,6 +395,10 @@
             <li class="nav-item" data-level="3"><a href="#table-construction-errors" class="nav-link">Table construction errors</a>
               <ul class="nav flex-column">
               </ul>
+            </li>
+            <li class="nav-item" data-level="3"><a href="#duplicate-pathname-error" class="nav-link">Duplicate pathname error</a>
+              <ul class="nav flex-column">
+              </ul>
             </li>
               </ul>
             </li>
@@ -632,6 +636,37 @@ <h3 id="table-construction-errors">Table construction errors</h3>
 <pre><code>ERROR : checkInit failed for type RSEVN interval(-2,2,-24)
 </code></pre>
 <p>The same kind of errors will happen when read and write indexes are incorrectly defined in a <code>rwtable</code> primitive. </p>
+<h3 id="duplicate-pathname-error">Duplicate pathname error</h3>
+<p>Pathnames for different GUI items have to be diffrent. Compiling the following code:</p>
+<pre><code>import(&quot;stdfaust.lib&quot;);
+nBands = 8;
+filterBank(N) = hgroup(&quot;Filter Bank&quot;,seq(i,N,oneBand(i)))
+with {
+    oneBand(j) = vgroup(&quot;[%j]Band&quot;,fi.peak_eq(l,f,b))
+    with {
+        a = j+1; // just so that band numbers don't start at 0
+        l = vslider(&quot;[2]Level[unit:db]&quot;,0,-70,12,0.01) : si.smoo;
+        f = nentry(&quot;[1]Freq&quot;,(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
+        b = f/hslider(&quot;[0]Q[style:knob]&quot;,1,1,50,0.01) : si.smoo;
+    };
+};
+process = filterBank(nBands);
+</code></pre>
+<p>gives the <code>ERROR : path '/Filter_Bank/Band/Q' is already used</code> message. This is because we typically want to distinguish pathnames to be controlled by OSC messages for instance. So a proper solution would be to rewrite the code with:</p>
+<pre><code>import(&quot;stdfaust.lib&quot;);
+nBands = 8;
+filterBank(N) = hgroup(&quot;Filter Bank&quot;,seq(i,N,oneBand(i)))
+with {
+    oneBand(j) = vgroup(&quot;[%j]Band %a&quot;,fi.peak_eq(l,f,b))
+    with {
+        a = j+1; // just so that band numbers don't start at 0
+        l = vslider(&quot;[2]Level[unit:db]&quot;,0,-70,12,0.01) : si.smoo;
+        f = nentry(&quot;[1]Freq&quot;,(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
+        b = f/hslider(&quot;[0]Q[style:knob]&quot;,1,1,50,0.01) : si.smoo;
+    };
+};
+process = filterBank(nBands);
+</code></pre>
 <h2 id="mathematical-functions-out-of-domain-errors">Mathematical functions out of domain errors</h2>
 <p>Error messages will be produced when the mathematical functions are used outside of their domain, and if the problematic computation is done at compile time. If the out of domain computation may be done at runtime, then a warning can be produced using the <code>-me</code> option (see <a href="#warning-messages">Warning messages</a> section).</p>
 <h3 id="modulo-primitive-error">Modulo primitive error</h3>

docs/manual/faq/index.html

@@ -366,6 +366,10 @@
               <ul class="nav flex-column">
               </ul>
             </li>
+            <li class="nav-item" data-level="2"><a href="#pathnames-in-the-gui-items" class="nav-link">Pathnames in the GUI items</a>
+              <ul class="nav flex-column">
+              </ul>
+            </li>
             <li class="nav-item" data-level="2"><a href="#surprising-effects-of-vgrouphgroup-on-how-controls-and-parameters-work" class="nav-link">Surprising effects of vgroup/hgroup on how controls and parameters work</a>
               <ul class="nav flex-column">
               </ul>
@@ -484,6 +488,46 @@ <h2 id="what-is-the-situation-about-faust-compiler-licence-and-the-deployed-code
 <p><em>Question: Does the Faust license (LGPL) apply somehow to the code exports that it produces as well? Or can the license of the exported code be freely chosen such that one could develop commercial software (e.g. VST plug-ins) using Faust?</em></p>
 <p>Answer: You can freely use Faust to develop commercial software. The LGPL license of the compiler <em>doesn't</em> apply to the code generated by the compiler. </p>
 <p>The license of the code generated by the Faust compiler depends only on the licenses of the input files. You should therefore check the licenses of the Faust libraries used and the architecture files. On the whole, when used unmodified, Faust libraries and architecture files are compatible with commercial, non-open source use.</p>
+<h2 id="pathnames-in-the-gui-items">Pathnames in the GUI items</h2>
+<p>Compiling the following code:</p>
+<pre><code>import(&quot;stdfaust.lib&quot;);
+nBands = 8;
+filterBank(N) = hgroup(&quot;Filter Bank&quot;,seq(i,N,oneBand(i)))
+with {
+    oneBand(j) = vgroup(&quot;[%j]Band&quot;,fi.peak_eq(l,f,b))
+    with {
+        a = j+1; // just so that band numbers don't start at 0
+        l = vslider(&quot;[2]Level[unit:db]&quot;,0,-70,12,0.01) : si.smoo;
+        f = nentry(&quot;[1]Freq&quot;,(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
+        b = f/hslider(&quot;[0]Q[style:knob]&quot;,1,1,50,0.01) : si.smoo;
+    };
+};
+process = filterBank(nBands);
+</code></pre>
+<p>gives the <code>ERROR : path '/Filter_Bank/Band/Q' is already used</code> message. This is because we typically want to distinguish pathnames to be controlled by OSC messages for instance. So a proper solution would be to rewrite the code with:</p>
+<pre><code>import(&quot;stdfaust.lib&quot;);
+nBands = 8;
+filterBank(N) = hgroup(&quot;Filter Bank&quot;,seq(i,N,oneBand(i)))
+with {
+    oneBand(j) = vgroup(&quot;[%j]Band %a&quot;,fi.peak_eq(l,f,b))
+    with {
+        a = j+1; // just so that band numbers don't start at 0
+        l = vslider(&quot;[2]Level[unit:db]&quot;,0,-70,12,0.01) : si.smoo;
+        f = nentry(&quot;[1]Freq&quot;,(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
+        b = f/hslider(&quot;[0]Q[style:knob]&quot;,1,1,50,0.01) : si.smoo;
+    };
+};
+process = filterBank(nBands);
+</code></pre>
+<p>to produce this GUI:</p>
+<p><img src="pathname.png" class="mx-auto d-block" width="50%">
+<center><em>Distinct GUI items to have different pathnames </em></center></p>
+<p>The rules ares the following:</p>
+<ul>
+<li>Two input control cannot have a same path (ERROR)</li>
+<li>An input control and a bargraph cannot have the same path (ERROR)</li>
+<li>Two bargraph can have the same path (<a href="../errors/#warning-messages">WARNING</a>)</li>
+</ul>
 <h2 id="surprising-effects-of-vgrouphgroup-on-how-controls-and-parameters-work">Surprising effects of vgroup/hgroup on how controls and parameters work</h2>
 <p>User interface widget primitives like <code>button</code>, <code>vslider/hslider</code>, <code>vbargraph/hbargraph</code> allow for an abstract description of a user interface from within the Faust code. They can be grouped in a hierarchical manner using <code>vgroup/hgroup/tgroup</code> primitives. Each widget then has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label.</p>
 <p>Widgets that have the <strong>same path</strong> in the hierarchical structure will correspond to a same controller and will appear once in the GUI. For instance the following DSP code does not contain any explicit grouping mechanism:</p>

src/manual/errors.md

@@ -357,6 +357,44 @@ ERROR : checkInit failed for type RSEVN interval(-2,2,-24)
 
 The same kind of errors will happen when read and write indexes are incorrectly defined in a `rwtable` primitive. 
 
+### Duplicate pathname error
+
+Pathnames for different GUI items have to be diffrent. Compiling the following code:
+
+```
+import("stdfaust.lib");
+nBands = 8;
+filterBank(N) = hgroup("Filter Bank",seq(i,N,oneBand(i)))
+with {
+    oneBand(j) = vgroup("[%j]Band",fi.peak_eq(l,f,b))
+    with {
+        a = j+1; // just so that band numbers don't start at 0
+        l = vslider("[2]Level[unit:db]",0,-70,12,0.01) : si.smoo;
+        f = nentry("[1]Freq",(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
+        b = f/hslider("[0]Q[style:knob]",1,1,50,0.01) : si.smoo;
+    };
+};
+process = filterBank(nBands);
+```
+
+gives the `ERROR : path '/Filter_Bank/Band/Q' is already used` message. This is because we typically want to distinguish pathnames to be controlled by OSC messages for instance. So a proper solution would be to rewrite the code with:
+
+```
+import("stdfaust.lib");
+nBands = 8;
+filterBank(N) = hgroup("Filter Bank",seq(i,N,oneBand(i)))
+with {
+    oneBand(j) = vgroup("[%j]Band %a",fi.peak_eq(l,f,b))
+    with {
+        a = j+1; // just so that band numbers don't start at 0
+        l = vslider("[2]Level[unit:db]",0,-70,12,0.01) : si.smoo;
+        f = nentry("[1]Freq",(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
+        b = f/hslider("[0]Q[style:knob]",1,1,50,0.01) : si.smoo;
+    };
+};
+process = filterBank(nBands);
+```
+
 ## Mathematical functions out of domain errors
 
 Error messages will be produced when the mathematical functions are used outside of their domain, and if the problematic computation is done at compile time. If the out of domain computation may be done at runtime, then a warning can be produced using the `-me` option (see [Warning messages](#warning-messages) section).
@@ -377,7 +415,6 @@ ERROR : % by 0 in IN[0] % 0
 
 The same kind of errors will be produced for `acos`, `asin`, `fmod`, `log10`, `log`, `remainder` and `sqrt` functions.
 
-
 ## FIR and backends related errors 
 
 Some primitives of the language are not available in some backends.
@@ -388,15 +425,15 @@ fun = ffunction(float fun(float), <fun.h>, "");
 process = fun;
 ```
 
- compiled with the wast/wasm backends using: `faust -lang wast errors.dsp` will produce the following error:
+compiled with the wast/wasm backends using: `faust -lang wast errors.dsp` will produce the following error:
 
  ```
 ERROR : calling foreign function 'fun' is not allowed in this compilation mode
  ```
 
- and the same kind of errors would happen also with foreign variables or constants. 
+and the same kind of errors would happen also with foreign variables or constants. 
 
- [TO COMPLETE]
+[TO COMPLETE]
 
 ## Compiler option errors
 

src/manual/faq.md

@@ -156,6 +156,56 @@ Answer: You can freely use Faust to develop commercial software. The LGPL licens
 
 The license of the code generated by the Faust compiler depends only on the licenses of the input files. You should therefore check the licenses of the Faust libraries used and the architecture files. On the whole, when used unmodified, Faust libraries and architecture files are compatible with commercial, non-open source use.
 
+
+## Pathnames in the GUI items
+
+Compiling the following code:
+
+```
+import("stdfaust.lib");
+nBands = 8;
+filterBank(N) = hgroup("Filter Bank",seq(i,N,oneBand(i)))
+with {
+    oneBand(j) = vgroup("[%j]Band",fi.peak_eq(l,f,b))
+    with {
+        a = j+1; // just so that band numbers don't start at 0
+        l = vslider("[2]Level[unit:db]",0,-70,12,0.01) : si.smoo;
+        f = nentry("[1]Freq",(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
+        b = f/hslider("[0]Q[style:knob]",1,1,50,0.01) : si.smoo;
+    };
+};
+process = filterBank(nBands);
+```
+
+gives the `ERROR : path '/Filter_Bank/Band/Q' is already used` message. This is because we typically want to distinguish pathnames to be controlled by OSC messages for instance. So a proper solution would be to rewrite the code with:
+
+```
+import("stdfaust.lib");
+nBands = 8;
+filterBank(N) = hgroup("Filter Bank",seq(i,N,oneBand(i)))
+with {
+    oneBand(j) = vgroup("[%j]Band %a",fi.peak_eq(l,f,b))
+    with {
+        a = j+1; // just so that band numbers don't start at 0
+        l = vslider("[2]Level[unit:db]",0,-70,12,0.01) : si.smoo;
+        f = nentry("[1]Freq",(80+(1000*8/N*(j+1)-80)),20,20000,0.01) : si.smoo;
+        b = f/hslider("[0]Q[style:knob]",1,1,50,0.01) : si.smoo;
+    };
+};
+process = filterBank(nBands);
+```
+
+to produce this GUI:
+
+<img src="pathname.png" class="mx-auto d-block" width="50%">
+<center>*Distinct GUI items to have different pathnames *</center>
+
+The rules ares the following:
+
+- Two input control cannot have a same path (ERROR)
+- An input control and a bargraph cannot have the same path (ERROR)
+- Two bargraph can have the same path ([WARNING](errors.md#warning-messages))
+
 ## Surprising effects of vgroup/hgroup on how controls and parameters work
 
 User interface widget primitives like `button`, `vslider/hslider`, `vbargraph/hbargraph` allow for an abstract description of a user interface from within the Faust code. They can be grouped in a hierarchical manner using `vgroup/hgroup/tgroup` primitives. Each widget then has an associated path name obtained by concatenating the labels of all its surrounding groups with its own label.