Janus,

I find this discussion on tonality-series and tonality-map very informative. It seems to me that the documentation of both these functions could be substantially improved. For instance, I spent much time trying to understand tonality-series, but without much headway:

1) Where exactly would you use this function?

2) The argument list mentions the keyword "shift" and there is an example of its use, but what does this do? When to use it?

3) What is the role of "assoc"?

4) Should we supply "root" always, if not what is the default?

5) What is the meaning of "fixed"?

6) What is the use of "variant"?

 

It was not obvious to me by looking at the documentation, that the first argument could be something like '((c4 maj) (f4 m)). In this case, the root is already specified, so should we additionally include :root '(c4 f4)? It appears unnecessary (I tried and it worked!) But for Torsten's sample code, I would not have guessed this possibility. And I know guessing is not always good in programming!

 

Cross-references are also useful if this function is related to others.

 

Having said this, I know how hard it is to document!

 

-Rangarajan

Will improve the doc soon - if time permit.