move pink-noise comparisons from demos.lib to noises.lib pink_noise doc

demos.lib

@@ -1332,38 +1332,6 @@ pospass_demo(x) = analytic_signal, modulator : si.cmul with {
   // modulator(n) = exp(sqrt(-1) * 2 * ma.PI * df * n / ma.SR) // if complex ok
 };
 
-//----------------------------`(dm.)pink_noise_demo`-------------------------
-// Illustrate and compare methods for generating pink noise.
-//
-// #### Usage
-//
-// ```
-// echo 'import("stdfaust.lib");' > pink_noise_demo.dsp
-// echo 'process = dm.pink_noise_demo;' >> pink_noise_demo.dsp
-// faust2octave pink_noise_demo.dsp
-// Octave:1> semilogx(20*log10(abs(fft(faustout,8192))(1:4096,:)));
-// ...
-// ```
-//
-// #### Output Figure
-//
-// <img alt="pink_noise_demo figure" src="https://ccrma.stanford.edu/wiki/Images/8/86/Tpinkd.jpg" width="600" />
-//
-//------------------------------------------------------------
-// Author: Julius Smith
-// License: MIT
-pink_noise_demo = pink_noises with {
-    f0 = 35; // Lower bandlimit in Hz
-    bw3 = 0.7 * ma.SR/2.0 - f0; // Bandwidth in Hz, 3rd order case
-    bw9 = 0.8 * ma.SR/2.0 - f0; // Bandwidth in Hz, 9th order case
-    pink_tilt_3 = fi.spectral_tilt(3,f0,bw3,-0.5);
-    pink_tilt_9 = fi.spectral_tilt(9,f0,bw9,-0.5);
-    pink_noises = 1-1' <:
-      no.pink_filter, // original designed by invfreqz in Octave
-      pink_tilt_3,    // newer method using the same filter order
-      pink_tilt_9;    // newer method using a higher filter order
-};
-
 // end jos section
 /************************************************************************
 ************************************************************************

filters.lib

@@ -2331,13 +2331,14 @@ peak_eq_rm(Lfx,fx,tanPiBT) = _ <: _,A,_ : +,- : *(0.5),*(K/2.0) : + with {
 //         between -1 and 1 (ln mag / ln radian freq)
 //
 // #### Examples
-// See `spectral_tilt_demo`.
+// See `dm.spectral_tilt_demo` and the documentation for `no.pink_noise`.
 //
 // #### Reference
 // J.O. Smith and H.F. Smith,
 // "Closed Form Fractional Integration and Differentiation via Real Exponentially Spaced Pole-Zero Pairs",
 // arXiv.org publication arXiv:1606.06154 [cs.CE], June 7, 2016,
 // <http://arxiv.org/abs/1606.06154>
+//
 //------------------------------------------------------------
 declare spectral_tilt author "Julius O. Smith III";
 declare spectral_tilt copyright "Copyright (C) 2003-2019 by Julius O. Smith III <[email protected]>";

noises.lib

@@ -124,20 +124,47 @@ Michon and/or Julius O. Smith III, and are released under the
 ************************************************************************/
 
 //---------------------------`(no.)pink_noise`--------------------------
-// Pink noise (1/f noise) generator (third-order approximation).
-// Use fi.spectral_tilt(order,lowerBandLimit,Bandwidth,-0.5)
-// to customize the design and adapt to any sampling rate, etc.
+// Pink noise (1/f noise) generator (third-order approximation covering the audio band well).
 // `pink_noise` is a standard Faust function.
 //
 // #### Usage
-//
 // ```
 // pink_noise : _
 // ```
 //
-// #### Reference:
-//
+// #### Reference
 // <https://ccrma.stanford.edu/~jos/sasp/Example_Synthesis_1_F_Noise.html>
+//
+// #### Alternatives
+// Higher-order approximations covering any frequency band can be obtained using
+// ```
+// no.noise : fi.spectral_tilt(order,lowerBandLimit,Bandwidth,p)
+// ```
+// where `p=-0.5` means filter rolloff `f^(-1/2)` which gives 1/f rolloff in the
+// power spectral density, and can be changed to other real values.
+//
+// #### Example
+// // pink_noise_compare.dsp - compare three pinking filters
+//
+// process = pink_noises with {
+//     f0 = 35; // Lower bandlimit in Hz
+//     bw3 = 0.7 * ma.SR/2.0 - f0; // Bandwidth in Hz, 3rd order case
+//     bw9 = 0.8 * ma.SR/2.0 - f0; // Bandwidth in Hz, 9th order case
+//     pink_tilt_3 = fi.spectral_tilt(3,f0,bw3,-0.5);
+//     pink_tilt_9 = fi.spectral_tilt(9,f0,bw9,-0.5);
+//     pink_noises = 1-1' <:
+//       no.pink_filter, // original designed by invfreqz in Octave
+//       pink_tilt_3,    // newer method using the same filter order
+//       pink_tilt_9;    // newer method using a higher filter order
+// };
+//
+// #### Output of Example
+// ```
+// faust2octave pink_noise_compare.dsp
+// Octave:1> semilogx(20*log10(abs(fft(faustout,8192))(1:4096,:)));
+// ...
+// ```
+// <img alt="pink_noise_demo figure" src="https://ccrma.stanford.edu/wiki/Images/8/86/Tpinkd.jpg" width="600" />
 //------------------------------------------------------------
 pink_filter = fi.iir((0.049922035, -0.095993537, 0.050612699, -0.004408786),
                     (-2.494956002, 2.017265875, -0.522189400));