search

sonic-pi-net / sonic-pi

Code. Music. Live.
https://sonic-pi.net
Other
10.8k stars 922 forks source link

Update Lang Documentation to include dot methods #1581

Open joesh1 opened 7 years ago

joesh1 commented 7 years ago

Hi, I'd suggest some simple updates for the help file. I have noticed in the examples/help files expressions which are not explained elsewhere. If you're used to code, they are indeed fairly self explanatory, otherwise it would be good to give people some explanation, even if only to clarify.

Here's an example from A.13 "Bringing it all together": n = (scale :e1, :minor_pentatonic).take(3).choose

I maybe looked in the wrong place, but I can't find any mention of .take, maybe there should be a small comment added in the help file?

If I come across more I'll drop them in here.

nicoder commented 7 years ago

Hi Joe,

take is described in the tutorial, in chapter 8.5, Ring Chains.

You would like to see it listed in the 'Lang' tab of the help system?

nico

On Thu, Mar 23, 2017 at 12:45 PM, Joe Higham notifications@github.com wrote:

Hi, I'd suggest some simple updates for the help file. I have noticed in the examples/help files expressions which are not explained elsewhere. If you're used to code, they are indeed fairly self explanatory, otherwise it would be good to give people some explanation, even if only to clarify.

Here's an example: live_loop :multi_beat do use_random_seed 2000 8.times do c = rrand(70, 130) n = (scale :e1, :minor_pentatonic).take(3).choose synth :tb303, note: n, release: 0.1, cutoff: c if rand < 0.9 sample :elec_hi_snare if one_in(6) sample :drum_cymbal_closed if one_in(2) sample :drum_cymbal_pedal if one_in(3) sample :bd_haus, amp: 1.5 if one_in(4) sleep 0.125 end end

I maybe looked in the wrong place, but I can't find any mention of .take, maybe there should be a small comment added in the help file?

If I come across more I'll drop them in here.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/samaaron/sonic-pi/issues/1581, or mute the thread https://github.com/notifications/unsubscribe-auth/AAWSmvn91IYVYoGAiG_ZwaMYrFZPnD9_ks5roltxgaJpZM4MmoUL .

joesh1 commented 7 years ago

Yes, I think that would be more logical. I find that good help files/system can make such a difference. I'm a Supercollider user and as you maybe know (I'm sure you do) it's major weakness is the helpfiles, which have plenty of information, but sometimes a bit chaotic.

I feel that if a work/expression is used in the code examples, it needs its own category, even if it just says "see Ring Chains", as an example. Another possibility (more work I guess) is to make a link within the helpfile code, so that if you select an expression it automatically sends you to the right place.

Great work though, I'm working on getting familiar so as to introduce in my school classes. It takes a bit of getting used to after SC ... ;-).

samaaron commented 6 years ago

Unfortunately there's currently no logical place to put dot methods (as opposed to functions) in the documentation system.

I think perhaps it might be nice to consider having a support list of 'kinds' number, strings, rings, etc. and then for each kind have a list of supported dot methods.

Unfortunately it's not currently on the top of my TODO list - but I'd be very happy to discuss this with someone else willing to take it on.

Dreat commented 4 years ago

@samaaron I can help with documenting dot methods. Can you elaborate on "support list of kinds"? You mean, doc page for number, string, rings etc? Meaning - this is what you can do with number? Do I get this correctly?