crow 4.0 doc suggestions

[dndrks]

starting an issue to collect feedback from folks on discord re: crow 4.0 docs!

• hotswap
• seeded random
• sequins v2
• timeline
• updated reference

[jaseknighter]

i'm a bit confused by the explanation in the timeline doc about pre and post.

the doc states timelines are different than sequins because timelines have methods applied applied "before and after," but it doesn't explain exactly what they can be applied before and after (e.g., they can be applied before or after they are initiated?).

similarly, the docs states "You'll only use queue or launch at the beginning." it would help to explain the beginning of what (e.g. at the beginning before the timeline starts executing).

[trentgill]

@jaseknighter agreed this is a confusing.

for reference (and to try to dial into what we're trying to say), when i saw "pre" and "post", the "centre" (ie the thing you put methods before and after) is the core function that takes the time-event-pairs table. this is loop{}, score{} or real{}.

in timeline, the thing that actually runs the timeline, is one of those 3 core functions (loop, score, real). all the pre & post methods modify that core function's behaviour. does this make sense?

if so, i guess we should make a point of giving these 3 core functions a special name. even calling them the "core" functions should be fine, but perhaps there's a better word. for me it's all about "the function that takes the timeline table". ahhh "timeline table" is confusing too!

"core functions (loop, score, real) take the time-event table that describes your timeline's action over time. all pre-methods go before this function, where post-methods come after"

example usage:

t = timeline.queue() -- won't start immediately. call `:play()` to start it
  :loop{} -- time-event table
  :times(n)
t:play() -- start the timeline

timeline.launch(n) -- set launch quantization to n beats
  :loop{} -- time-event table
  :unless(f) -- f is a boolean, or a predicate function that returns a boolean

timeline.queue():launch(n) -- queue it, and set launch quantization
  :score{} -- time-event table

timeline.queue():launch(n)
  :real{} -- time-event table

[jaseknighter]

@trentgill, thanks for the explanation. i think i understand how this works better now. looking over the doc again, i think this statement is very helpful: "Pre-methods are about changing when a timeline will begin, whereas post-methods are about how they run, or when they will stop"

regarding the name of the "core functions," i was thinking what makes them core, is they set the 'mode' of the timeline.

[trentgill]

@jaseknighter glad this helped clarify things.

my hesitation about calling them the mode functions, is modality is something i think of as modifying another thing. but these functions both 1) set the mode, and 2) are where you describe the meaning of the timeline.

i guess it is quite similar to the input[n].mode() function though, so perhaps mode is the word most aligned to our existing codebase.

perhaps @dndrks has other thoughts (they've always had great naming ideas!)

[dndrks]

in the docs, trent naturally used "the behavior of the main function (loop, score, or real)", so i'm happy to just refer to those three as the 'main' timeline functions, which are augmented by the presence of pre- and post-methods.

but also, just to confirm (@trentgill): only loop has post-methods, right? score and real only have the special "reset" entry, so maybe just clarifying the stuff y'all brought up through the docs is enough?

[trentgill]

@dndrks yes indeed. i feel like i've made the description overly complicated by talking about pre&post in such general terms. there's only 4 'extra' methods in total, and 2 of them are loop only!

i guess i was leaving room for more of this stuff in the future (to respond to common things people other than myself want to do with the library), but that is premature optimization to be sure! i think we should probably just talk about adding "pre" methods for launch&queue. then have a separate section about loop conditions where we can describe unless and times as a special-feature of loop.

[jaseknighter]

(EDIT: resolved in crow 4.0.1...no additional documentation required)

re: hotswapping sequins...

i was thinking i could apply an arithmetic operator hotswapped sequins like:

hs.melody = s{0,4,7,11} + 2

but it doesn't appear to work.

however, this appears to work:

hs.melody = hs.melody + 2

assuming my findings are correct, i'd say it would help to have a section in the hotswap doc about applying operators and provides an example or two.

also, based on my very basic understanding of how it works, there are a couple of points that would be worth highlighting:

1. operators can only be applied after a hotswaped sequins has been created
2. as a result of point 1 above, the operator has to be applied to the hotswap object, like:

hs.melody = s{0,4,7,11} 
hs.melody = hs.melody + 2

[trentgill]

@jaseknighter i fixed the behaviour you mentioned. you were correct that hotswapping a sequins where the change is the addition of a transformer wouldn't work, but now it does.

in general, i'd say your intuition as to how it should work was correct, there was just a couple bugs that precluded this from happening which are now fixed.

[dndrks]

rad, everything's been launched! thank you @jaseknighter for the fantastic feedback + invaluable test driving!!