Extempore reference manual?

[Kyle Barbour]

Hello all,

Does Extempore have a complete reference manual somewhere? I've read
through and am aware of <https://extemporelang.github.io/docs/> and
<https://digego.github.io/extempore/>, but these differ from most
other languages I've worked in by not having a set of pages that
simply explain what the available functions and such are and what
arguments they take, etc. I've tried reading through Sorenson's thesis
<https://openresearch-repository.anu.edu.au/handle/1885/144603>, which
helped somewhat but didn't seem to document how to actually code in the
language. I'm able to make Extempore produce (some) sound but it's hard
to figure out how to become proficient without there being some sort of
reference that explains what the functions, arguments, etc. are.

In case it's not clear what I'm looking for, here are some examples from
other languages:

- TidalCycles: https://tidalcycles.org/index.php/All_the_functions
- FoxDot: https://docs.foxdot.org/
- SuperCollider: http://doc.sccode.org/Overviews/Classes.html

I really, really love what Extempore seems to be able to do, but am just
getting stuck learning more and would love it if there was some sort of
reference I could read through. I've read the Little Schemer and am
working through SICP in order to understand Extempore better, but even
with that the specifics of Extempore's operation is still pretty obtuse
to me.

Thanks for any thoughts!

--
Kyle Barbour
Never mind the balrogs.
ky...@kylebarbour.org / (415) 238-9953
Rochester, NY

[Andrew Sorensen]

Hi Kyle,

No, I'm afraid there isn't any comprehensive documentation.  Which is indeed a shame.  

The problem goes quite deep - did you know for example that Extempore has support for symbolic computation (i.e. symbolic differentiation/integration, simplification etc..).

While it is possible to *generate* a big list of functions (definitions), this has been done in the past and providing function definitions hasn't really proven all that useful without additional *descriptive* documentation.

Unfortunately there are no easy wins with this *descriptive* documentation - it requires time and effort, which is best supported by a strong community. 

Community is a bit of a chicken and egg problem - a strong community helps to build documentation & documentation helps to build a strong community.

Interested to hear your thoughts/suggestions though.

Cheers,

Andrew.

--
You received this message because you are subscribed to the Google Groups "Extempore" group.
To unsubscribe from this group and stop receiving emails from it, send an email to extemporelan...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Toby Gifford]

symbolic algebra? cool! where can I find those functions?

[Andrew Sorensen]

check out examples/contrib/cas

[Andrew Sorensen]

nb. the windows binary ships with cas support, can't remember if the osx binary did

[Kyle Barbour]

Andrew,

Thanks so much for the thoughtful reply! I really appreciate it.

Is that list available or easy to generate? (Sorry, I'm just not experienced enough to easily figure that out on my own.) If so maybe that would be a good community / wiki-style project, at least at first. I wouldn't mind trying to document some of it as I'm gradually figuring it out and submitting PRs, I'm just not super sure where to start and I think even just having a list of the function definitions might provide a starting point.

What do you think?

Kyle

January 16, 2019 4:57 PM, "Andrew Sorensen" <dig...@gmail.com> wrote:

> Hi Kyle,
>
> No, I'm afraid there isn't any comprehensive documentation. Which is indeed a shame.
>
> The problem goes quite deep - did you know for example that Extempore has support for symbolic
> computation (i.e. symbolic differentiation/integration, simplification etc..).
>
> While it is possible to *generate* a big list of functions (definitions), this has been done in the
> past and providing function definitions hasn't really proven all that useful without additional
> *descriptive* documentation.
>
> Unfortunately there are no easy wins with this *descriptive* documentation - it requires time and
> effort, which is best supported by a strong community.
>
> Community is a bit of a chicken and egg problem - a strong community helps to build documentation &
> documentation helps to build a strong community.
>
> Interested to hear your thoughts/suggestions though.
>
> Cheers,
> Andrew.
>
> On Wed, Jan 16, 2019 at 5:25 PM Kyle Barbour <ky...@kylebarbour.org> wrote:
>
>> Hello all,
>>
>> Does Extempore have a complete reference manual somewhere? I've read

>> through and am aware of <https://extemporelang.github.io/docs> and
>> <https://digego.github.io/extempore>, but these differ from most

>> other languages I've worked in by not having a set of pages that
>> simply explain what the available functions and such are and what
>> arguments they take, etc. I've tried reading through Sorenson's thesis
>> <https://openresearch-repository.anu.edu.au/handle/1885/144603>, which
>> helped somewhat but didn't seem to document how to actually code in the
>> language. I'm able to make Extempore produce (some) sound but it's hard
>> to figure out how to become proficient without there being some sort of
>> reference that explains what the functions, arguments, etc. are.
>>
>> In case it's not clear what I'm looking for, here are some examples from
>> other languages:
>>
>> - TidalCycles: https://tidalcycles.org/index.php/All_the_functions
>> - FoxDot: https://docs.foxdot.org

[Ben Swift]

Hi Kyle

I can weigh in on this - since I wrote that stuff.

The "auto-generate the docs/reference list" stuff (such as it is) is in
`runtime/llvmti.xtm:11315` and following. The basic idea is this:

1. load all the extempore libs you're interested in (e.g. libs/core/math.xtm)
2. call (xtmdoc-export-caches-to-json FILE-PATH INCLUDE-NATIVEFUNCS?)
3. do something with the output json

The actual data works in a few ways:

- it interrogates the runtime for type information (args, return type) for
xtlang funcs
- it knows about xtlang docstrings, and can even parse out jsdoc-style
structured comments so that you can provide documentation on individual
arguments
- it uses get-closure-code to get arg names at least for any scheme functions

Now, as Andrew said, this is only as good as the manual documentation
(e.g docstrings), which at the time (and still) isn't very good. So not
much was done with it.

If we did want to give it another push, probably the best way to do it
is:

1. go through and add good docstrings to at least the core libraries

2. generate the json data

3. incorporate that into an "API docs" section of the
<https://extemporelang.github.io> website (which @cyblue9 has made some nice
improvements to recently)

4. ?

5. profit.

Ideally, steps 2&3 could/should be automated.


Anyway, if you're interested then grepping through the main extempore
repo for "xtmdoc" will probably be the best option. I'm 100% sure it's
bitrotted since I wrote it, and may need some work to even use atm. Feel
free to ping me back with more specific questions.

Cheers,
Ben

[Yuya Chiba]

Hi Kyle

I am learning extempore about 6 month ago.

It was hard for me to understand how to use the functions.

So, I read extempore source code on github.

And I am working to add comment(argument and return value and example and easy explain) to each functions.(https://github.com/digego/extempore/issues/339)

I believe that it helps beginners(me and some others) to understand extempore.

(I completed to add comment of libs/core/pc_ivl.xtm functions about 90%. But, I still don't sent PR. Sorry...)

If many functions have comment, we can generate API reference automatically.

What do you think?

(by the way, Scheme don't support docstrings, do it?)

I found interesting stuff. 

http://hacks.michelepasin.org/extempore/

How good it is!!

Perhaps, He might create extempore API generator.

If below API reference(ex: http://hacks.michelepasin.org/extempore/7489) explains argument and return value etc, It is a very good stuff!!!! 

I am intresting to create docs. So, I want to help you :)

Best Regards,

Yuya Chiba(@cyblue9)

2019年1月17日木曜日 11時39分40秒 UTC+9 ben:

[Michele Pasin]

Hi Yuya

I've created http://hacks.michelepasin.org/extempore/ a while ago essentially cause I had the same need you have. The lack of docstrings was a problem, although (at least for me) being able to quickly search&inspect the source code of a function was a great way to learn the language.

The web app source is based on python/django [1], and the rather basic parser I was using can be found here [2]

I wouldn't mind updating it at some point.. possibly using the JSON generated by the scripts mentioned by Ben above. I'll look into it. 

Any feedback or help much appreciated! (ps feel free to open an issue on github)

Cheers

Michele

[1] https://github.com/lambdamusic/django-extempore-docs

[2] https://github.com/lambdamusic/django-extempore-docs/blob/master/management/commands/parse.py

[Yuya Chiba]

Hi Michele

Thank you for reply!

> The lack of docstrings was a problem, although (at least for me) being able to quickly search&inspect the source code of a function was a great way to learn the language.

Yes, that's right.

> I wouldn't mind updating it at some point.. possibly using the JSON generated by the scripts mentioned by Ben above. I'll look into it. 

Nice! I can't wait for updating!

I will look your repository!

P.S.

I often listen to your music (https://vimeo.com/18044771)

Nice rythme!

Best Regards,

Yuya Chiba

2019年2月4日月曜日 19時46分06秒 UTC+9 Michele Pasin:

[Kyle Barbour]

On Thu, Jan 17, 2019 at 01:39:35PM +1100, Ben Swift wrote:
>Anyway, if you're interested then grepping through the main extempore
>repo for "xtmdoc" will probably be the best option. I'm 100% sure it's
>bitrotted since I wrote it, and may need some work to even use atm. Feel
>free to ping me back with more specific questions.

Thanks so much for this extremely informative email! I really appreciate
it. As I free up some time to work on this more I will try to contribute
as you suggest and I'm sure I'll have lots of questions for you then and
will reach out :)

[Kyle Barbour]

Hey Yuya!

Thanks so much for your email! Really appreciate it. That's a super
helpful reference.

Kyle

>> Kyle Barbour <ky...@kylebarbour.org <javascript:>> writes:
>>
>> > Andrew,
>> >
>> > Thanks so much for the thoughtful reply! I really appreciate it.
>> >
>> > Is that list available or easy to generate? (Sorry, I'm just not
>> experienced
>> > enough to easily figure that out on my own.) If so maybe that would be a
>> good
>> > community / wiki-style project, at least at first. I wouldn't mind
>> trying to
>> > document some of it as I'm gradually figuring it out and submitting PRs,
>> I'm
>> > just not super sure where to start and I think even just having a list
>> of the
>> > function definitions might provide a starting point.
>> >
>> > What do you think?
>> >
>> > Kyle
>> >
>> >
>> > January 16, 2019 4:57 PM, "Andrew Sorensen" <dig...@gmail.com

>> >>> ky...@kylebarbour.org <javascript:> / (415) 238-9953

>> >>> Rochester, NY
>> >>>
>> >>> --
>> >>> You received this message because you are subscribed to the Google
>> Groups
>> >>> "Extempore" group.
>> >>> To unsubscribe from this group and stop receiving emails from it, send
>> an
>> >>> email to

>> >>> extemporelan...@googlegroups.com <javascript:>.

>> >>> For more options, visit https://groups.google.com/d/optout.
>> >>
>> >> --
>> >> You received this message because you are subscribed to the Google
>> Groups
>> >> "Extempore" group.
>> >> To unsubscribe from this group and stop receiving emails from it, send
>> an
>> >> email to

>> >> extemporelan...@googlegroups.com <javascript:>.

>> >> For more options, visit https://groups.google.com/d/optout.
>> >
>> > --
>> > Kyle Barbour
>> > Never mind the balrogs.

>> > ky...@kylebarbour.org <javascript:> / (415) 238-9953

[Ben Swift]

No worries. One day Extempore will be so well documented that it doesn't
rely on Andy and I writing informative emails to this list. But not
today :)

Cheers

Ben

Kyle Barbour <ky...@kylebarbour.org> writes:

[geor...@bigpond.net.au]

Michele

It has been handy having a pinned tab to your hacks site.

But now it doesn't work any more.

Has something happened at your end?

Hope you are well

Regards

George

[Michele Pasin]

Hi George 

That's right it's offline now unfortunately. The hosting provider I had for years stopped working so I'm in the process of migrating a bunch of stuff.

I'm planning to serve the whole thing using Github pages, as a static app.  That'll also make it easier for others to contribute / extend the code base.

I will post a message when that's done :-) 

To view this discussion on the web visit https://groups.google.com/d/msgid/extemporelang/6e676e9e-79c7-490f-83a5-e3be99138815n%40googlegroups.com.

--

----

Thanks, Michele

Email: michel...@gmail.com   

Web: http://www.michelepasin.org

[George Wright]

Nice to hear from you again Michele.

Looking forward to the hacks reappearing.

At the moment I am trying to become familiar with Ardour6.

Been neglecting Extempore for a while - will get back to it soon.

Regards

George

George Wright

geor...@bigpond.net.au

You received this message because you are subscribed to a topic in the Google Groups "Extempore" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/extemporelang/4rPzUdH_6ww/unsubscribe.
To unsubscribe from this group and all its topics, send an email to extemporelan...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/extemporelang/CAE_o1-Ki8KqFtzZ4dWXczvkXwn9XAVjDA9moRHtZJYe5MVQy3w%40mail.gmail.com.

[Michele Pasin]

Hey George, all

The functions index website is back online here: https://extempore.michelepasin.org/

Source code is on Github, in case you're interested: https://github.com/lambdamusic/xtm-docs

Cheers and happy livecoding :-)

To view this discussion on the web visit https://groups.google.com/d/msgid/extemporelang/62F11162-4DA2-44EE-8C12-923CD9B58DE0%40bigpond.net.au.

[George Wright]

Thanks Michele

Looks good from here.

Regards

George

George Wright

geor...@bigpond.net.au

To view this discussion on the web visit https://groups.google.com/d/msgid/extemporelang/CAE_o1-Jy56sTEQboJzJfidfxJQc0-9iv8tvhRY8eR5xqfWsQoA%40mail.gmail.com.