Thank you, Yann for the hints,
the faust json foo.dsp seems to be a good option for metadata.
For the markdown convention
An SC UGen documentation for SinOSC would as a minimum need to contain:
Class Methods:
ar (freq: 440, phase: 0, mul: 1, add: 0)
Arguments:
freq Frequency in Hertz. Sampled at audio-rate.
phase Phase in radians. Sampled at audio-rate.
NOTE: phase values should be within the range +-8pi. If
larger then simply use .mod(2pi) to wrap them.
mul Output will be multiplied by this value.
add This value will be added to the output.
This could be done with the markdown convention.
It would be cool though, if we could also programmatically handle multiple
inputs, for multichannel situations e.g. Ambisonics, a fifth order Azimuth
rotator for SC (derived from Pierre's ambitools) would then look like
ar (in1, in2, in3, in4, in5, in6, in7, in8, in9, in10, in11, in12, in13,
in14, in15, in16, in17, in18, in19, in20, in21, in22, in23, in24, in25,
in26, in27, in28, in29, in30, in31, in32, in33, in34, in35, in36, azimuth:
0)
When generating the SC help file based on the documentation in the dsp
file, we would possibly like to group the first numbered 36 inputs in the
documentation, followed by the azimuth.
Since there are macros for generating multichannel input wires in Faust,
maybe documentation could be integrated.
Also documenting the output in terms of what process returns, in this case,
a 36 chan B-format, would be great.
I like to think that these are things beneficial beyond the SC specific
documentation, like documenting inlets and outlet in Pd MaxMSP etc.
Cheers,
Florian
www.grond.at
On Thu, Jun 15, 2017 at 8:31 AM, Yann Orlarey <orla...@grame.fr> wrote:
> Hi Florian,
>
> Extending the automatic documentation system is certainly possible, but
> would require some extra work. Two other (easier) possibilities could be:
> - use the same markdown convention that we use for the standard faust
> libraries (see documentation/library.pdf/contributing page 15),
> - declare your own metadata in the source code and process the json file
> "foo.dsp.json" resulting from "faust -json foo.dsp".
>
> Can you give an example of how you would like ideally to document your
> code?
>
> Cheers
>
> Yann
>
>
> -------------------------
>
> Yann Orlarey
> Directeur scientifique
> www.grame.fr
>
>
>
> 2017-06-14 16:41 GMT+02:00 Florian Grond <floriangr...@gmail.com>:
>
>> Hello,
>>
>> A group of SuperCollider devs started discussing what a best practice for
>> integrating Faust-based SuperCollider plugins should look like. One idea
>> that came up was to automate SuperCollider helpfile generation inspired by
>> the faust2mathdoc script.
>>
>> In a SuperCollider helpfile we would need to be able to document all the
>> input arguments and also what the UGen returns. Now thinking outside the
>> needs of SuperCollider, this would conform with documenting the inlets and
>> outlets of MaxMSP or PureData and possibly similar needs on other platforms
>> too.
>>
>> The documentation in chapter 11
>> http://faust.grame.fr/images/faust-quick-reference.pdf
>> lists 6 specific tags:
>> mdoc, equation, diagram, metadata, notice, listing.
>>
>> None of them seems specifically dedicated to the arguments of the UGen or
>> to what the UGen would return e.g. how many audio channels etc.
>>
>> Questions A) What tag do you suggest? Should a new specific tag be
>> introduced? How can documentation be best autogenerated based on the Faust
>> code, the wires and what process returns?
>>
>> Also, we think that the Faust code might possibly contain data structures
>> that would be worth translating into Class variables of the SuperCollider
>> language side representation the UGen.
>> To give an example, I've used many times the Ambisonics decoder toolbox
>> which generates Ambisonics decoders as dsp files based on MATLAB code.
>> Here it would be fantastic if there was a way to document speaker
>> positions in the .dsp file and to translate them into a class variable in
>> SuperCollider. I imagine that there are other cases where similar needs
>> exist.
>>
>> Question B) What would be the best way to achieve that? how could these
>> types of data best be handled/documented so that it can be passed on to the
>> documentation in other platforms?
>>
>> Florian
>>
>>
>>
>>
>>
>>
>>
>> ------------------------------------------------------------
>> ------------------
>> Check out the vibrant tech community on one of the world's most
>> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
>> _______________________________________________
>> Faudiostream-users mailing list
>> Faudiostream-users@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/faudiostream-users
>>
>>
>
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Faudiostream-users mailing list
Faudiostream-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/faudiostream-users
