Discussion:
[chuck-users] FLOSS (user editable) manual for ChucK
Tomasz Kaye's brain
2009-11-27 09:39:44 UTC
Permalink
Hi all. I noticed that there doesn't seem to currently be a user
editable version of the ChucK manual online
(http://wiki.cs.princeton.edu/index.php/ChucK/Manual this page is the
nearest thing i found).

While learning things there have been a few cases where I thought
small changes to the manual wording would make things clearer (for
instance my recent question about how Envelope works).

I wondered about moving a copy of the ChucK manual to FLOSS Manuals,
where it can be edited by users.
http://en.flossmanuals.net/flossmanuals.

I used this site in a recent Ardour booksprint I took part in. It's
not perfect (sometimes navigation is a little unintuitive), but works
well. It uses version history (different versions can be compared
too). A user is appointed as a maintainers of a particular manual.
Chapters can be edited by anyone with a FLOSS account, but maintainers
get to decide when new versions of chapters are 'published' (made
visible in the canonical version of the FLOSS manual, the one that
guest visitors to the FLOSS manuals site will see)
http://en.flossmanuals.net/FLOSSManuals/Maintainers .

A few preliminary questions about the idea:

@Ge: would you be okay with the current manual being copied to another
site, and edited? (i couldn't find license details on the current
manual).

What do people think of this idea in general?
Would people use it?
Would it greatly confuse matters to have one more url for ChucK
documentation? (any other issues?)
Adam Tindale
2009-11-27 17:53:41 UTC
Permalink
Hi,

Great to see you here. I am the current documentation maintainer and
have been absent for a long time now. I love your ideas but I would
love to make some suggestions before we jump in.

Firstly, I would like to announce to you all that I successfully
defended my PhD this week and now that is done I will be spending more
time here collecting the great ideas that come through this list.

Second, the manual is open source and I strongly encourage editing but
it is currently only available through CVS and it is formatted via
LaTeX. This has been a major barrier for getting collaborators.

Presently I am working on converting the manual to asciidoc, which is
a simple formatting language that produces both html and pdf copies.
This will allow us to keep the manual and the website in sync. This
has been a sore point for a long time now.

I have signed up for a github account and I would be happy to put the
chuck manual there. This will allow everyone to grab from my branch
and then I can pull changes from everyone and then commit them back to
the project. How does that sound?

Future. I want to have a documentation sprint. How does December 19th
look? Anyone else interested? I would be online all day giving out
tasks and helping people get into the technical parts of adding to our
document and also looking for snippets of wisdom or errata to improve
the minutia.

In the meantime, I will work out the details to push changes up to the site.

I think that too much fragmentation of the project is not good. Ge has
done a great job and keeping everything together and I think that is
one of the reasons we have so many people here. It is easy to find
information (or to find out that the information doesn't exist) and it
is easy to ask questions to a list that actually responds. Having a
dev or working version of the docs is good but having it all in one
place for newbies definitely eases the transition, so I don't want to
break that "feature."

These are my current thoughts. What do you think?

--art

On Fri, Nov 27, 2009 at 1:39 AM, Tomasz Kaye's brain
Post by Tomasz Kaye's brain
Hi all. I noticed that there doesn't seem to currently be a user
editable version of the ChucK manual online
(http://wiki.cs.princeton.edu/index.php/ChucK/Manual this page is the
nearest thing i found).
While learning things there have been a few cases where I thought
small changes to the manual wording would make things clearer (for
instance my recent question about how Envelope works).
I wondered about moving a copy of the ChucK manual to FLOSS Manuals,
where it can be edited by users.
http://en.flossmanuals.net/flossmanuals.
I used this site in a recent Ardour booksprint I took part in. It's
not perfect (sometimes navigation is a little unintuitive), but works
well. It uses version history (different versions can be compared
too). A user is appointed as a maintainers of a particular manual.
Chapters can be edited by anyone with a FLOSS account, but maintainers
get to decide when new versions of chapters are 'published' (made
visible in the canonical version of the FLOSS manual, the one that
guest visitors to the FLOSS manuals site will see)
http://en.flossmanuals.net/FLOSSManuals/Maintainers .
@Ge: would you be okay with the current manual being copied to another
site, and edited? (i couldn't find license details on the current
manual).
What do people think of this idea in general?
Would people use it?
Would it greatly confuse matters to have one more url for ChucK
documentation? (any other issues?)
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-11-27 22:20:31 UTC
Permalink
Adam;

Great to see you here.


Yes, isn't it? I was enjoying Tomasz's posts elsewhere for a few years now
before running into him at Steim. It's a small world.
Post by Adam Tindale
Firstly, I would like to announce to you all that I successfully
defended my PhD this week and now that is done I will be spending more
time here collecting the great ideas that come through this list.
Both are great news! congratulations! What is your PhD on?
Post by Adam Tindale
Presently I am working on converting the manual to asciidoc, which is
a simple formatting language that produces both html and pdf copies.
This will allow us to keep the manual and the website in sync. This
has been a sore point for a long time now.
Right, this is a good point. The threshold of entry should be lower there so
everyone who would like to help can. I think most of the more senior users
have their own field of expertise that many others will know less about and
of course new users will see issues that the rest overlooks. To me the
manual is a important thing as it will be the first port of call for many
people who are considering ChucK; that's also why I felt the recent
compilation issues needed a quick fix. If we don't make a good first
impression we'll never reach world-domination.
Post by Adam Tindale
I have signed up for a github account and I would be happy to put the
chuck manual there. This will allow everyone to grab from my branch
and then I can pull changes from everyone and then commit them back to
the project. How does that sound?
Good. But then we need a intro to this. A intro to using this system aimed
at people who are not routinely using version management. Like me :-).
Post by Adam Tindale
Future. I want to have a documentation sprint. How does December 19th
look? Anyone else interested? I would be online all day giving out
tasks and helping people get into the technical parts of adding to our
document and also looking for snippets of wisdom or errata to improve
the minutia.
This sounds like a good idea, and very fitting with the inspiration Tomasz
here took from the recent Ardour sprint in Rotterdam and online.

Let me commit to covering the interaction between DSP in code and in UGens;
that's a interesting topic that I feel has so far been under-appreciated
even though it's one of the things where ChucK can really shine as compared
to other systems.

I think that too much fragmentation of the project is not good. Ge has
Post by Adam Tindale
done a great job and keeping everything together and I think that is
one of the reasons we have so many people here. It is easy to find
information (or to find out that the information doesn't exist) and it
is easy to ask questions to a list that actually responds. Having a
dev or working version of the docs is good but having it all in one
place for newbies definitely eases the transition, so I don't want to
break that "feature."
I respectfully disagree there. I do agree that Ge is doing a amazing job
that can't be praised highly enough but the information is not all in one
place. Most is in the manual but then some things are only in the examples
or even just mentioned in Ge's thesis (whole chunks of that should likely be
pasted straight into the manual). Then there are things that are only
mentioned in the list archives or on the forum or WiKi, hinted at in the old
docs on the site or even just in the VERSIONS file. I think there are also
bits that aren't documented at all; there must be as every once in a while
something pops up that has been implemented but never documented.

Of course this has so far not been a great issue as the scene is still small
enough for the people who know how to find it all to answer all questions
and this can certainly be attributed to Ge who set the tone of friendly help
to all comers (quite unlike some lists I hear about).

To pick just one thing; just the other day I was talking about the "repeat"
structure in ChucK on the Toplap list when debating the influence of syntax
on musical movements (as well as kissing as a quantitative measurement of
musical quality; it's a wonderful list). Even I myself can't remember where
I found that one (might be Ge's thesis?). The manual mentions it's
existence, but not how it works;

repeat(3)
{
<<<"this will be printed three times">>>;
}

...a wonderful device, it can be used immediately even if you have just seen
it once so it's a great introduction to loops, it's simplicity makes it
great for casual impulsive livecoding with a drink at hand, but don't ask me
where it's documented.

These are my current thoughts. What do you think?
Yes, yes, yes &yes. Great ideas, it's good to see you back on the case and
we'll do this. I'm in and I hope we'll see a strong turnout of people
writing, suggesting and proof-reading.

After this I'd like a sprint on the /examples/ dir. There are some bits in
there that I find questionable. We can debate style (some structures have
become out-dated) but I feel they should all run without errors or warnings
(this is not currently the case) and there are some otherwise dubious bits
here and there. I think I kept some notes on those somewhere but might have
misplaced them.

Great initiative!
Kas.
mike clemow
2009-11-27 23:38:18 UTC
Permalink
+1 for community manual.

I would love to help. Also, I'd be glad to rally any and all
Chuckists I know to book-sprint on it if need be. Whatever the
documentation solution is, please let us know how to help.

Mike
Post by Kassen
Adam;
Post by Adam Tindale
Great to see you here.
Yes, isn't it? I was enjoying Tomasz's posts elsewhere for a few years now
before running into him at Steim. It's a small world.
Post by Adam Tindale
Firstly, I would like to announce to you all that I successfully
defended my PhD this week and now that is done I will be spending more
time here collecting the great ideas that come through this list.
Both are great news! congratulations! What is your PhD on?
Post by Adam Tindale
Presently I am working on converting the manual to asciidoc, which is
a simple formatting language that produces both html and pdf copies.
This will allow us to keep the manual and the website in sync. This
has been a sore point for a long time now.
Right, this is a good point. The threshold of entry should be lower there so
everyone who would like to help can. I think most of the more senior users
have their own field of expertise that many others will know less about and
of course new users will see issues that the rest overlooks. To me the
manual is a important thing as it will be the first port of call for many
people who are considering ChucK; that's also why I felt the recent
compilation issues needed a quick fix. If we don't make a good first
impression we'll never reach world-domination.
Post by Adam Tindale
I have signed up for a github account and I would be happy to put the
chuck manual there. This will allow everyone to grab from my branch
and then I can pull changes from everyone and then commit them back to
the project. How does that sound?
Good. But then we need a intro to this. A intro to using this system aimed
at people who are not routinely using version management. Like me :-).
Post by Adam Tindale
Future. I want to have a documentation sprint. How does December 19th
look? Anyone else interested? I would be online all day giving out
tasks and helping people get into the technical parts of adding to our
document and also looking for snippets of wisdom or errata to improve
the minutia.
This sounds like a good idea, and very fitting with the inspiration Tomasz
here took from the recent Ardour sprint in Rotterdam and online.
Let me commit to covering the interaction between DSP in code and in UGens;
that's a interesting topic that I feel has so far been under-appreciated
even though it's one of the things where ChucK can really shine as compared
to other systems.
Post by Adam Tindale
I think that too much fragmentation of the project is not good. Ge has
done a great job and keeping everything together and I think that is
one of the reasons we have so many people here. It is easy to find
information (or to find out that the information doesn't exist) and it
is easy to ask questions to a list that actually responds. Having a
dev or working version of the docs is good but having it all in one
place for newbies definitely eases the transition, so I don't want to
break that "feature."
I respectfully disagree there. I do agree that Ge is doing a amazing job
that can't be praised highly enough but the information is not all in one
place. Most is in the manual but then some things are only in the examples
or even just mentioned in Ge's thesis (whole chunks of that should likely be
pasted straight into the manual). Then there are things that are only
mentioned in the list archives or on the forum or WiKi, hinted at in the old
docs on the site or even just in the VERSIONS file. I think there are also
bits that aren't documented at all; there must be as every once in a while
something pops up that has been implemented but never documented.
Of course this has so far not been a great issue as the scene is still small
enough for the people who know how to find it all to answer all questions
and this can certainly be attributed to Ge who set the tone of friendly help
to all comers (quite unlike some lists I hear about).
To pick just one thing; just the other day I was talking about the "repeat"
structure in ChucK on the Toplap list when debating the influence of syntax
on musical movements (as well as kissing as a quantitative measurement of
musical quality; it's a wonderful list). Even I myself can't remember where
I found that one (might be Ge's thesis?). The manual mentions it's
existence, but not how it works;
repeat(3)
  {
  <<<"this will be printed three times">>>;
  }
...a wonderful device, it can be used immediately even if you have just seen
it once so it's a great introduction to loops, it's simplicity makes it
great for casual impulsive livecoding with a drink at hand, but don't ask me
where it's documented.
Post by Adam Tindale
These are my current thoughts. What do you think?
Yes, yes, yes &yes. Great ideas, it's good to see you back on the case and
we'll do this. I'm in and I hope we'll see a strong turnout of people
writing, suggesting and proof-reading.
After this I'd like a sprint on the /examples/ dir. There are some bits in
there that I find questionable. We can debate style (some structures have
become out-dated) but I feel they should all run without errors or warnings
(this is not currently the case) and there are some otherwise dubious bits
here and there. I think I kept some notes on those somewhere but might have
misplaced them.
Great initiative!
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
Tomasz Kaye's brain
2009-11-28 00:12:55 UTC
Permalink
Hi Adam, thanks for the reply.
Post by Adam Tindale
Second, the manual is open source and I strongly encourage editing but
it is currently only available through CVS and it is formatted via
LaTeX. This has been a major barrier for getting collaborators.
LaTeX is really neat, but it is a hard sell!
Post by Adam Tindale
I have signed up for a github account and I would be happy to put the
chuck manual there. This will allow everyone to grab from my branch
and then I can pull changes from everyone and then commit them back to
the project. How does that sound?
Perhaps responders to this thread can indicate if they have experience
working with git or other similar scm, to gauge how much of a barrier
this might be.

I'm comfortable working with git. But i wonder how many other
chuckists are used to scm systems. I underestimated the difficulty
with which new users can get to grips with a scm system; A few months
back i tried to encourage the max/msp using monome community to adopt
git (and github) to avoid the fragmentation i was seeing with many
different versions of monome apps. I posted a tutorial on how to use
git for max, evangelised about the benefits, but for whatever reason
it didn't work out. I think this was because for most people the tech
barrier with git (or any scm) was too high.

I think chuck users are more likely to be used to a scm system
already, but if i were choosing how to publish editable ChucK
documentation, i think i'd still choose for a web based editing system
like FLOSS manuals, because it'd be a shame to have technology get in
the way of people feeling as though they can contribute.
Post by Adam Tindale
I want to have a documentation sprint. How does December 19th
look? Anyone else interested?
Damn!, i'm very much interested but I'll be away from computers
between the 17 and 21st of december
Kassen
2009-11-28 00:34:20 UTC
Permalink
Tomasz;

Perhaps responders to this thread can indicate if they have experience
Post by Tomasz Kaye's brain
working with git or other similar scm, to gauge how much of a barrier
this might be.
Sadly none. I'm up for anything as long as there are some pointers and a
assurance that i can't break anything.
Post by Tomasz Kaye's brain
I'm comfortable working with git. But i wonder how many other
chuckists are used to scm systems. I underestimated the difficulty
with which new users can get to grips with a scm system; A few months
back i tried to encourage the max/msp using monome community to adopt
git (and github) to avoid the fragmentation i was seeing with many
different versions of monome apps. I posted a tutorial on how to use
git for max, evangelised about the benefits, but for whatever reason
it didn't work out. I think this was because for most people the tech
barrier with git (or any scm) was too high.
Ok. So we need some info on why this is a good idea here and how to use it
for this purpose. It'd be especially good if it were fun and easy as well.

If need be we may need to add a wiki page, or simple list posts to this. I
suspect there are quie a few lurkers here, people who have questions they
feel might be silly, and that's exactly the kind of person who could make a
very important contribution here so I feel we should try to make that sort
of thing as easy as possible.

There is more to manuals that the letter of the text anyway so we may need
more layers than just a method to add text; questions might be at least as
valuable in this case. In my earlier post I took a subject I'd like to write
on just because I had questions on that before myself... but maybe this
isn't a topic that a lot of people are fighting with. Maybe MIDI-out is much
more important to a more people; I have some gut-feelings but I don't know
for sure.
Post by Tomasz Kaye's brain
I think chuck users are more likely to be used to a scm system
already, but if i were choosing how to publish editable ChucK
documentation, i think i'd still choose for a web based editing system
like FLOSS manuals, because it'd be a shame to have technology get in
the way of people feeling as though they can contribute.
I could see how that would help, yes. Is this practical on Adam's end at
all? What systems are there and can we get those installed somewhere?

Kas.
Adam Tindale
2009-11-28 06:00:31 UTC
Permalink
Hey All,

This discussion is very encouraging. I have long hoped for a few more
eyes when writing the docs and not after I have moved on to other
projects.

December 19th was an arbitrary date. How about we do the 16th since
Tomasz can make that? I would really love a git expert around. If you
guys haven't seen his tutorial on git with max, it is really
wonderful.

LaTeX has proven to be bad for many reasons. Asciidoc will be the new
build system. I'll compile relevant documentation over the next few
weeks so we can get going. The main benefit is that there is very
little markup. So, if anyone has an idea all we will need is a plain
text file or an email. It will be that simple to modify the
documentation.

Kas. Your response are quick and thoughtful. I can see why you
disagree. For me the community has outgrown the current state of the
manual. In the beginning when we were all digging our teeth in it was
a great resource but now we hunger for more. I think for a beginner it
still serves as a great reference but it needs more.

I also agree with you that the next major place to fix up is the
examples directory.

I am also thinking we need to split the manual into two major sections
or possibly two documents, like Cycling 74 does. The max/msp manuals
are incredible. The reference manual is just that while there is
another manual for tutorials. Ours could be tutorials and code
snippets. I haven't thought about this idea for too long but I thought
I would see if it had any resonance.

I have been looking through FLOSS manuals a bit. It might be a good
place to have a scratch manual but I don't know about giving it all up
to an outside source. Two issues for me: is there a way I can easily
suck down the working version to include with the distribution and if
we migrated to the site would Ge be cool with that?

We have a wiki. I would be more interested in reinvigorating that
space for this project. Maybe we could decide at the end of the sprint
that we have outgrown it but I would like to make sure that is the
answer before committing to hard to another site.

Let's spend some time picking tools and then we will move forward. We
should spend the day getting things done, not fighting with tech or
intellectual property issues.

--art

ps. Kas, my thesis will become live once the final Ts are crossed. You
may find some ChucK code in it ;)
Post by Kassen
Tomasz;
Post by Tomasz Kaye's brain
Perhaps responders to this thread can indicate if they have experience
working with git or other similar scm, to gauge how much of a barrier
this might be.
Sadly none. I'm up for anything as long as there are some pointers and a
assurance that i can't break anything.
Post by Tomasz Kaye's brain
I'm comfortable working with git. But i wonder how many other
chuckists are used to scm systems. I underestimated the difficulty
with which new users can get to grips with a scm system; A few months
back i tried to encourage the max/msp using monome community to adopt
git (and github) to avoid the fragmentation i was seeing with many
different versions of monome apps. I posted a tutorial on how to use
git for max, evangelised about the benefits, but for whatever reason
it didn't work out. I think this was because for most people the tech
barrier with git (or any scm) was too high.
Ok. So we need some info on why this is a good idea here and how to use it
for this purpose. It'd be especially good if it were fun and easy as well.
If need be we may need to add a wiki page, or simple list posts to this. I
suspect there are quie a few lurkers here, people who have questions they
feel might be silly, and that's exactly the kind of person who could make a
very important contribution here so I feel we should try to make that sort
of thing as easy as possible.
There is more to manuals that the letter of the text anyway so we may need
more layers than just a method to add text; questions might be at least as
valuable in this case. In my earlier post I took a subject I'd like to write
on just because I had questions on that before myself... but maybe this
isn't a topic that a lot of people are fighting with. Maybe MIDI-out is much
more important to a more people; I have some gut-feelings but I don't know
for sure.
Post by Tomasz Kaye's brain
I think chuck users are more likely to be used to a scm system
already, but if i were choosing how to publish editable ChucK
documentation, i think i'd still choose for a web based editing system
like FLOSS manuals, because it'd be a shame to have technology get in
the way of people feeling as though they can contribute.
I could see how that would help, yes. Is this practical on Adam's end at
all? What systems are there and can we get those installed somewhere?
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-11-28 09:14:44 UTC
Permalink
Adam;

December 19th was an arbitrary date. How about we do the 16th since
Post by Adam Tindale
Tomasz can make that? I would really love a git expert around. If you
guys haven't seen his tutorial on git with max, it is really
wonderful.
I'm fine with anything. I'll have a friend over for much of December but
will make time for this. I might make him try on the tutorials as a
test-case :-)
Post by Adam Tindale
LaTeX has proven to be bad for many reasons. Asciidoc will be the new
build system. I'll compile relevant documentation over the next few
weeks so we can get going. The main benefit is that there is very
little markup. So, if anyone has an idea all we will need is a plain
text file or an email. It will be that simple to modify the
documentation.
That sounds like a good match for my experience level with markup :-)
Post by Adam Tindale
Kas. Your response are quick and thoughtful. I can see why you
disagree.
I don't think we actually disagreed, it was just the literal statement that
you made that I didn't feel was literally true. I took that opportunity to
point out in what ways the material that we need (nearly all of it exists in
some form or other) is scattered.
Post by Adam Tindale
For me the community has outgrown the current state of the
manual. In the beginning when we were all digging our teeth in it was
a great resource but now we hunger for more. I think for a beginner it
still serves as a great reference but it needs more.
Absolutely. I think this is a sign of a larger phenomenon; the community is
"growing up" and people are trying more ambitious projects. I also think
that's where the current set of issues with the type system come from. Those
bugs were probably there but previously we weren't extending classes,
passing them to functions, casting up and down a bit, then expecting the
result to fit into a array.

I am also thinking we need to split the manual into two major sections
Post by Adam Tindale
or possibly two documents, like Cycling 74 does. The max/msp manuals
are incredible. The reference manual is just that while there is
another manual for tutorials. Ours could be tutorials and code
snippets. I haven't thought about this idea for too long but I thought
I would see if it had any resonance.
I agree. In a way this is already the structure of the manual. To me a good
structure would be;

*Introduction (welcome and how to install ChucK at all)
*Basics
-how to make a beep
-flow control
-basic structures
(This stuff should cover enough to give a frame of reference for everything
else but not overwhelm)
*In depth consideration of topics
-concurrency
-what good are classes and functions
-events
-how does this UGen graph stuff work
-how to not hate MIDI (tricky subject :-) )
-etc.
(This stuff would basically document every major part in a friendly tone)
*Reference
-all UGens
-all operators
-all keywords
-all member functions
-etc
(Everything, and verified, but just the factual basics)

This is roughly the structure we already have, but the current manual has
some holes in it.

I have been looking through FLOSS manuals a bit. It might be a good
Post by Adam Tindale
place to have a scratch manual but I don't know about giving it all up
to an outside source. Two issues for me: is there a way I can easily
suck down the working version to include with the distribution and if
we migrated to the site would Ge be cool with that?
Those are good questions. We also need Ge's call on on to what degree it
will be ok to grab useful bits from his thesis. That text does reserve all
rights while the manual to ChucK should probably have some sort of license
that is compatible with the major Linux distributions (because it would be
good to get packages in the future). I'm not sure what concerns play a role
there but let's find out before we run into issues later on.

I'd like to include at least the discussion of the structure of the VM in
the manual as that text -while mainly of interest to more experienced users-
is great for framing how it all fits together and *why* things are like they
are.
Post by Adam Tindale
Let's spend some time picking tools and then we will move forward. We
should spend the day getting things done, not fighting with tech or
intellectual property issues.
Yes. One option would be Google's new "wave" thing as well. I'm chiefly
suggesting that because I want to try it out. The WiKi is already there,
open to anyone, and we do know that it works for some things for some
people, unlike Wave. We also know that it tends to slowly become a mess if
not watched by somebody taking care of a page.

Another note; I bet that this push is going to unearth a slew of;
a) bugs.
b) things that may look like bugs and are instead features that are a bit
confused.
c) things that are certainly not bugs but simply labelled in the wrong way

Let's try to catch all of those in a centralised way as well to make the
most of our work and time.

ps. Kas, my thesis will become live once the final Ts are crossed. You
Post by Adam Tindale
may find some ChucK code in it ;)
In that case I would love to get a pdf in due time.

Yours,
Kas.
Tomasz Kaye's brain
2009-11-28 09:31:42 UTC
Permalink
@kassen
"[bugs] Let's try to catch all of those in a centralised way as well
to make the most of our work and time."

Yes. That reminds me (slightly OT) , would it not be a good idea that
a issue tracking system was used for ChucK? This is up to the devs
ultimately, but i think there must be some good free options around
and i can image it would make things easier (both for reporting and
for fixing).
Post by Kassen
Adam;
Post by Adam Tindale
December 19th was an arbitrary date. How about we do the 16th since
Tomasz can make that? I would really love a git expert around. If you
guys haven't seen his tutorial on git with max, it is really
wonderful.
I'm fine with anything. I'll have a friend over for much of December but
will make time for this. I might make him try on the tutorials as a
test-case :-)
Post by Adam Tindale
LaTeX has proven to be bad for many reasons. Asciidoc will be the new
build system. I'll compile relevant documentation over the next few
weeks so we can get going. The main benefit is that there is very
little markup. So, if anyone has an idea all we will need is a plain
text file or an email. It will be that simple to modify the
documentation.
That sounds like a good match for my experience level with markup :-)
Post by Adam Tindale
Kas. Your response are quick and thoughtful. I can see why you
disagree.
I don't think we actually disagreed, it was just the literal statement that
you made that I didn't feel was literally true. I took that opportunity to
point out in what ways the material that we need (nearly all of it exists in
some form or other) is scattered.
Post by Adam Tindale
For me the community has outgrown the current state of the
manual. In the beginning when we were all digging our teeth in it was
a great resource but now we hunger for more. I think for a beginner it
still serves as a great reference but it needs more.
Absolutely. I think this is a sign of a larger phenomenon; the community is
"growing up" and people are trying more ambitious projects.  I also think
that's where the current set of issues with the type system come from. Those
bugs were probably there but previously we weren't extending classes,
passing them to functions, casting up and down a bit, then expecting the
result to fit into a array.
Post by Adam Tindale
I am also thinking we need to split the manual into two major sections
or possibly two documents, like Cycling 74 does. The max/msp manuals
are incredible. The reference manual is just that while there is
another manual for tutorials. Ours could be tutorials and code
snippets. I haven't thought about this idea for too long but I thought
I would see if it had any resonance.
I agree. In a way this is already the structure of the manual. To me a good
structure would be;
*Introduction (welcome and how to install ChucK at all)
*Basics
-how to make a beep
-flow control
-basic structures
(This stuff should cover enough to give a frame of reference for everything
else but not overwhelm)
*In depth consideration of topics
-concurrency
-what good are classes and functions
-events
-how does this UGen graph stuff work
-how to not hate MIDI (tricky subject :-) )
-etc.
(This stuff would basically document every major part in a friendly tone)
*Reference
-all UGens
-all operators
-all keywords
-all member functions
-etc
(Everything, and verified, but just the factual basics)
This is roughly the structure we already have, but the current manual has
some holes in it.
Post by Adam Tindale
I have been looking through FLOSS manuals a bit. It might be a good
place to have a scratch manual but I don't know about giving it all up
to an outside source. Two issues for me: is there a way I can easily
suck down the working version to include with the distribution and if
we migrated to the site would Ge be cool with that?
Those are good questions. We also need Ge's call on on to what degree it
will be ok to grab useful bits from his thesis. That text does reserve all
rights while the manual to ChucK should probably have some sort of license
that is compatible with the major Linux distributions (because it would be
good to get packages in the future). I'm not sure what concerns play a role
there but let's find out before we run into issues later on.
I'd like to include at least the discussion of the structure of the VM in
the manual as that text -while mainly of interest to more experienced users-
is great for framing how it all fits together and *why* things are like they
are.
Post by Adam Tindale
Let's spend some time picking tools and then we will move forward. We
should spend the day getting things done, not fighting with tech or
intellectual property issues.
Yes. One option would be Google's new "wave" thing as well. I'm chiefly
suggesting that because I want to try it out. The WiKi is already there,
open to anyone, and we do know that it works for some things for some
people, unlike Wave. We also know that it tends to slowly become a mess if
not watched by somebody taking care of a page.
Another note; I bet that this push is going to unearth a slew of;
a) bugs.
b) things that may look like bugs and are instead features that are a bit
confused.
c) things that are certainly not bugs but simply labelled in the wrong way
Let's try to catch all of those in a centralised way as well to make the
most of our work and time.
Post by Adam Tindale
ps. Kas, my thesis will become live once the final Ts are crossed. You
may find some ChucK code in it ;)
In that case I would love to get a pdf in due time.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Adam Tindale
2009-11-28 19:22:21 UTC
Permalink
Upon further investigation there are a few other downsides to FLOSS manuals:

There is no provision for sections, just chapters

The document is created with HTML so layout possibilities are
limited not only by that markup but what the site is able to translate
to PDF

The PDFs don't look very good. CSS editing is possible but that
would probably require one person doing that for most of the day

The filenames of the downloaded items seems to be fixed to something
I don't like

The file sizes of the PDFs are huge

Making a title page doesn't seem as easy as it should be

It will take some time to get our current manual into their site to
start changing it

There are some major bonuses:

Nobody needs to learn a source control system (I think this is a
bummer actually but it does speed up the work process)

It will be easy to edit and update after the sprint

There are far more CSS masters out there than LaTeX masters. It
should be easier to get people to help with the layout and styles once
the content is up and running

-----

So, as I am looking at this I think the FLOSS manuals site is winning.
As for property issues since the site releases everything as GPL by
default then we are good. The current manual is also GPLed so there
are no problems on that front.

Depending on how fast this goes we could start moving content away
from the wiki. FLOSS manuals looks like it can replace both the
documentation station and the more bleeding edge idea centre.

I would like to make this decision in the next week so that I have
time to put the manual up where ever it will be in the format that we
are going to modify.

December 16th is in my calendar, is it in yours?

a

On Sat, Nov 28, 2009 at 1:31 AM, Tomasz Kaye's brain
Post by Tomasz Kaye's brain
@kassen
"[bugs] Let's try to catch all of those in a centralised way as well
to make the most of our work and time."
Yes. That reminds me (slightly OT) , would it not be a good idea that
a issue tracking system was used for ChucK? This is up to the devs
ultimately, but i think there must be some good free options around
and i can image it would make things easier (both for reporting and
for fixing).
Post by Kassen
Adam;
Post by Adam Tindale
December 19th was an arbitrary date. How about we do the 16th since
Tomasz can make that? I would really love a git expert around. If you
guys haven't seen his tutorial on git with max, it is really
wonderful.
I'm fine with anything. I'll have a friend over for much of December but
will make time for this. I might make him try on the tutorials as a
test-case :-)
Post by Adam Tindale
LaTeX has proven to be bad for many reasons. Asciidoc will be the new
build system. I'll compile relevant documentation over the next few
weeks so we can get going. The main benefit is that there is very
little markup. So, if anyone has an idea all we will need is a plain
text file or an email. It will be that simple to modify the
documentation.
That sounds like a good match for my experience level with markup :-)
Post by Adam Tindale
Kas. Your response are quick and thoughtful. I can see why you
disagree.
I don't think we actually disagreed, it was just the literal statement that
you made that I didn't feel was literally true. I took that opportunity to
point out in what ways the material that we need (nearly all of it exists in
some form or other) is scattered.
Post by Adam Tindale
For me the community has outgrown the current state of the
manual. In the beginning when we were all digging our teeth in it was
a great resource but now we hunger for more. I think for a beginner it
still serves as a great reference but it needs more.
Absolutely. I think this is a sign of a larger phenomenon; the community is
"growing up" and people are trying more ambitious projects.  I also think
that's where the current set of issues with the type system come from. Those
bugs were probably there but previously we weren't extending classes,
passing them to functions, casting up and down a bit, then expecting the
result to fit into a array.
Post by Adam Tindale
I am also thinking we need to split the manual into two major sections
or possibly two documents, like Cycling 74 does. The max/msp manuals
are incredible. The reference manual is just that while there is
another manual for tutorials. Ours could be tutorials and code
snippets. I haven't thought about this idea for too long but I thought
I would see if it had any resonance.
I agree. In a way this is already the structure of the manual. To me a good
structure would be;
*Introduction (welcome and how to install ChucK at all)
*Basics
-how to make a beep
-flow control
-basic structures
(This stuff should cover enough to give a frame of reference for everything
else but not overwhelm)
*In depth consideration of topics
-concurrency
-what good are classes and functions
-events
-how does this UGen graph stuff work
-how to not hate MIDI (tricky subject :-) )
-etc.
(This stuff would basically document every major part in a friendly tone)
*Reference
-all UGens
-all operators
-all keywords
-all member functions
-etc
(Everything, and verified, but just the factual basics)
This is roughly the structure we already have, but the current manual has
some holes in it.
Post by Adam Tindale
I have been looking through FLOSS manuals a bit. It might be a good
place to have a scratch manual but I don't know about giving it all up
to an outside source. Two issues for me: is there a way I can easily
suck down the working version to include with the distribution and if
we migrated to the site would Ge be cool with that?
Those are good questions. We also need Ge's call on on to what degree it
will be ok to grab useful bits from his thesis. That text does reserve all
rights while the manual to ChucK should probably have some sort of license
that is compatible with the major Linux distributions (because it would be
good to get packages in the future). I'm not sure what concerns play a role
there but let's find out before we run into issues later on.
I'd like to include at least the discussion of the structure of the VM in
the manual as that text -while mainly of interest to more experienced users-
is great for framing how it all fits together and *why* things are like they
are.
Post by Adam Tindale
Let's spend some time picking tools and then we will move forward. We
should spend the day getting things done, not fighting with tech or
intellectual property issues.
Yes. One option would be Google's new "wave" thing as well. I'm chiefly
suggesting that because I want to try it out. The WiKi is already there,
open to anyone, and we do know that it works for some things for some
people, unlike Wave. We also know that it tends to slowly become a mess if
not watched by somebody taking care of a page.
Another note; I bet that this push is going to unearth a slew of;
a) bugs.
b) things that may look like bugs and are instead features that are a bit
confused.
c) things that are certainly not bugs but simply labelled in the wrong way
Let's try to catch all of those in a centralised way as well to make the
most of our work and time.
Post by Adam Tindale
ps. Kas, my thesis will become live once the final Ts are crossed. You
may find some ChucK code in it ;)
In that case I would love to get a pdf in due time.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Michael Heuer
2009-11-28 20:01:03 UTC
Permalink
...
The most important feature for me would be support for ChucK source
code snippets. The wiki is completely broken in this regard -- each
line of code must start with a space character for some odd reason.

The source code snippets should also be importable from runnable bits
of source code, say the examples directory, not inlined directly into
the documentation. This way it is easy to keep all the source code in
the docs up-to-date, making sure they run properly with each new
version of ChucK.

michael
Kassen
2009-11-28 20:01:43 UTC
Permalink
Adam;

I don't think there is a need for all contributors to have to deal with
formatting of text. Something like very early html with headers, paragraph
breaks, a tag to indicate code and perhaps a few more things (but no fonts
and no colours) should do. That way a single designer (who need not be a
editor on the content level) could set appropriate fonts and related
settings for the whole thing in one swoop. Coherency is important here. I
see little benefit in letting everybody set their own font and think this
would make for a fatiguing read. Some people are very good at this and most
others don't really enjoy it so to me that seems like a easy choice.

Similarly, we'll need a standard for naming and indentation.

theExamples()
{
useThis();
}

..so let's stick to that, but let's formalise it as that will save time
later.

Ge's Thesis uses syntax highlighting for the code, while the manual doesn't.
I find the code in the thesis more easy on the eye. I think the thesis
follows the mini in highlighting, but it also seems to me that the mini's
highlighting is yet incomplete. Ge's thesis, as a file, is also much larger
than the current manual, btw, it's larger than the whole ChucK distribution.

Just some points of view.
Kas.
Tomasz Kaye's brain
2009-11-28 21:13:42 UTC
Permalink
 There is no provision for sections, just chapters
Judging from the existing manuals (looking at the bypassing internet
censorship one as an example), although the chapter is the main unit,
it looks like subheadings are taken into account too, at least when
generating PDF indexes.
 The document is created with HTML so layout possibilities are
limited not only by that markup but what the site is able to translate
to PDF
True. It may not be possible to get a 1-to-1 formatting transfer from
how the current manual is.
 The PDFs don't look very good. CSS editing is possible but that
would probably require one person doing that for most of the day
Although the initial styling work would be a pain, it might only be
necessary to do it once. I'm sure I'm not the only one here, but I'm
fairly handy with CSS (though I'm no designer or typesetter) and
wouldn't mind smartening it up with some rules in case better
qualified users aren't available.
 The filenames of the downloaded items seems to be fixed to something I don't like
Yeah the filenames of the exported PDFs are ugly, and non-descriptive,
which is a shame. Of course the exports that are destined for
distribution would get renamed.
 The file sizes of the PDFs are huge
The internet censorship manual is around 8Mb, but I noticed it has
lots of images, which I imagine are making it heavier.
 Making a title page doesn't seem as easy as it should be
Agreed.
It will take some time to get our current manual into their site to start changing it
Yes. Perhaps this could go relatively quickly if its a task we could
split among several people.
December 16th is in my calendar, is it in yours?
It is.
Scott Hewitt
2009-12-02 03:15:02 UTC
Permalink
Hi,

Perhaps we could all work on the wiki or in google wave (I have a few
invites if people need them) and then once the content is done work
out the presentation side.

The pdf manual is a great resource and the easy of turning it into a
physical object is great, I actually took my paper copy to the pub for
a few nights when I first started chuck.

However good documentation in my mind would also have a role online as
part of the wiki and maybe eventually as an integrated help system
perhaps within the miniAudicle.

So I would suggest that we aim to create / update the content of the
manual in a way which is as flexible as possible going forward.

just my two cents :)

scott

On Sat, Nov 28, 2009 at 9:13 PM, Tomasz Kaye's brain
Post by Tomasz Kaye's brain
Post by Adam Tindale
There is no provision for sections, just chapters
Judging from the existing manuals (looking at the bypassing internet
censorship one as an example), although the chapter is the main unit,
it looks like subheadings are taken into account too, at least when
generating PDF indexes.
Post by Adam Tindale
The document is created with HTML so layout possibilities are
limited not only by that markup but what the site is able to translate
to PDF
True. It may not be possible to get a 1-to-1 formatting transfer from
how the current manual is.
Post by Adam Tindale
The PDFs don't look very good. CSS editing is possible but that
would probably require one person doing that for most of the day
Although the initial styling work would be a pain, it might only be
necessary to do it once. I'm sure I'm not the only one here, but I'm
fairly handy with CSS (though I'm no designer or typesetter) and
wouldn't mind smartening it up with some rules in case better
qualified users aren't available.
Post by Adam Tindale
The filenames of the downloaded items seems to be fixed to something I don't like
Yeah the filenames of the exported PDFs are ugly, and non-descriptive,
which is a shame. Of course the exports that are destined for
distribution would get renamed.
Post by Adam Tindale
The file sizes of the PDFs are huge
The internet censorship manual is around 8Mb, but I noticed it has
lots of images, which I imagine are making it heavier.
Post by Adam Tindale
Making a title page doesn't seem as easy as it should be
Agreed.
Post by Adam Tindale
It will take some time to get our current manual into their site to start changing it
Yes. Perhaps this could go relatively quickly if its a task we could
split among several people.
Post by Adam Tindale
December 16th is in my calendar, is it in yours?
It is.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Adam Tindale
2009-12-02 06:25:58 UTC
Permalink
Michael - excellent suggestion. FLOSS Manuals seems to have a facility
for including code easily. Has anyone tried putting ChucK code in to
see if it barfs on it?

I think google wave would be confusing. FLOSS manuals has a chat
function and also the ability to make talk pages that aren't published
in the manual. That way we can make a list of ideas or errata and it
will not be included when a user downloads the pdf.

The final pdf produced by this will be included in the ChucK
distribution. I am happy to manage that migration when new versions of
either ChucK or the manual are released.

Scott - I am glad the manual was a friend at the bar. I took a
computer to the bar many times when learning ChucK and got many
strange looks when people looked at my screen. They all assumed I was
trying to steal their banking information.

Tomasz - I was referring to sections as being farther up the layout
tree than chapters. There are sections and subsections of chapters
that seem to do quite well in FLOSS manuals. What I am looking for is
a way to make a split in the manual between our tutorials and the
reference section. It isn't a pressing issue.

So, it looks like we have some CSS people who can look at the issues
here. FLOSS manuals looks terrible. Fortunately we have full access to
the CSS. I would love if someone were to spend some time with this
during the Christmas break. I know that Ge spent some time tweaking
the website layout. I wouldn't want to throw away too much of that
work. The colours and general typesetting make reading the ChucK
reference webpages very easy on the eyes.

The more I think about it the more I am strongly leaning towards FLOSS
manuals. The group we have assembled will work most efficiently that
way. If we migrate away from this after the sprint then that is ok,
but I would like to get as many people involved as possible to start
out.

Can we make a final decision by the end of this week? If we can then I
will start migrating the manual to the site.

Other collaboration possibilities: We use Wave or some sort of chat to
talk to each other while we use some other method for building the
docs. Right now they are in LaTeX and we could go with that system. I
would be happy to accept changes and ideas all day and then just put
them into the current system.

We could also use asciidoc. It is a great little documentation system
that has easy markup that easily compiles a pdf or generates a
website. This would allow us to keep our current site architecture.

If we go with either of these solutions (or another build system) then
we will need svn or git to manage the files and collaborations.
Although I see building the docs ourselves as a superior system, I see
the layers of tutorials we will need to do to get people up to speed.
That is a major downer.

These are my current sleepy thoughts.

--art
Post by Scott Hewitt
Hi,
Perhaps we could all work on the wiki or in google wave (I have a few
invites if people need them) and then once the content is done work
out the presentation side.
The pdf manual is a great resource and the easy of turning it into a
physical object is great, I actually took my paper copy to the pub for
a few nights when I first started chuck.
However good documentation in my mind would also have a role online as
part of the wiki and maybe eventually as an integrated help system
perhaps within the miniAudicle.
So I would suggest that we aim to create / update the content of the
manual in a way which is as flexible as possible going forward.
just my two cents :)
scott
On Sat, Nov 28, 2009 at 9:13 PM, Tomasz Kaye's brain
Post by Tomasz Kaye's brain
 There is no provision for sections, just chapters
Judging from the existing manuals (looking at the bypassing internet
censorship one as an example), although the chapter is the main unit,
it looks like subheadings are taken into account too, at least when
generating PDF indexes.
 The document is created with HTML so layout possibilities are
limited not only by that markup but what the site is able to translate
to PDF
True. It may not be possible to get a 1-to-1 formatting transfer from
how the current manual is.
 The PDFs don't look very good. CSS editing is possible but that
would probably require one person doing that for most of the day
Although the initial styling work would be a pain, it might only be
necessary to do it once. I'm sure I'm not the only one here, but I'm
fairly handy with CSS (though I'm no designer or typesetter) and
wouldn't mind smartening it up with some rules in case better
qualified users aren't available.
 The filenames of the downloaded items seems to be fixed to something I don't like
Yeah the filenames of the exported PDFs are ugly, and non-descriptive,
which is a shame. Of course the exports that are destined for
distribution would get renamed.
 The file sizes of the PDFs are huge
The internet censorship manual is around 8Mb, but I noticed it has
lots of images, which I imagine are making it heavier.
 Making a title page doesn't seem as easy as it should be
Agreed.
It will take some time to get our current manual into their site to start changing it
Yes. Perhaps this could go relatively quickly if its a task we could
split among several people.
December 16th is in my calendar, is it in yours?
It is.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Tomasz Kaye's brain
2009-12-02 09:24:02 UTC
Permalink
Hi Adam
Post by Adam Tindale
Michael - excellent suggestion. FLOSS Manuals seems to have a facility
for including code easily. Has anyone tried putting ChucK code in to
see if it barfs on it?
I asked Adam at FLOSS Manuals whether there was a sandbox there. There is a
partial one, a manual that can be used for testing things:
http://www.flossmanuals.net/bin/view/Testing

Unfortunately you can't publish it, to test exactly how it will appear to
the public, or to export it as a PDF.
I entered some ChucK code into a <pre> element. That seemed to work fine in
the preview. Though probably needs more testing (for instance, do long lines
inside a <pre> element automatically wrap in PDF export? my suspicion is
that they might not).

Tomasz - I was referring to sections as being farther up the layout
Post by Adam Tindale
tree than chapters. There are sections and subsections of chapters
that seem to do quite well in FLOSS manuals. What I am looking for is
a way to make a split in the manual between our tutorials and the
reference section. It isn't a pressing issue.
Right, I see.

So, it looks like we have some CSS people who can look at the issues
Post by Adam Tindale
here. FLOSS manuals looks terrible. Fortunately we have full access to
the CSS. I would love if someone were to spend some time with this
during the Christmas break. I know that Ge spent some time tweaking
the website layout. I wouldn't want to throw away too much of that
work. The colours and general typesetting make reading the ChucK
reference webpages very easy on the eyes.
You mean http://chuck.cs.princeton.edu/ right?
Post by Adam Tindale
The more I think about it the more I am strongly leaning towards FLOSS
manuals. The group we have assembled will work most efficiently that
way. If we migrate away from this after the sprint then that is ok,
but I would like to get as many people involved as possible to start
out.
I agree.

Other collaboration possibilities: We use Wave or some sort of chat to
Post by Adam Tindale
talk to each other while we use some other method for building the
docs. Right now they are in LaTeX and we could go with that system. I
would be happy to accept changes and ideas all day and then just put
them into the current system.
Right. Though not a pressing concern at the momoent, in a wave chat with
Kassen we both noticed unworkable lag when the number of 'blips' (messages)
got large. So unless that gets a fix soon, a simpler chat system might be
more appropriate, when we get to that stage.

Tomasz
Michael Heuer
2009-12-02 15:43:29 UTC
Permalink
Post by Tomasz Kaye's brain
Post by Adam Tindale
Michael - excellent suggestion. FLOSS Manuals seems to have a facility
for including code easily. Has anyone tried putting ChucK code in to
see if it barfs on it?
...
I entered some ChucK code into a <pre> element. That seemed to work fine in
the preview. Though probably needs more testing (for instance, do long lines
inside a <pre> element automatically wrap in PDF export? my suspicion is
that they might not).
Does FLOSS manuals have an import mechanism? This would be essential
for keeping the ChucK examples/snippets separate from the
documentation itself.

For instance, in APT documentation format

http://maven.apache.org/doxia/references/apt-format.html

there is a snippet macro

http://maven.apache.org/doxia/macros/index.html#Snippet_Macro

michael
Tomasz Kaye's brain
2009-12-02 16:06:49 UTC
Permalink
@Michael: I'm pretty confident that FLOSS Manuals doesn't have such a
dynamic code importing capability, or support for variables or dynamic
substitutions in general. So with FLOSS, code snippets would be 'hard coded'
into the documentation (I assumed that it was currently this way with the
LaTeX docs too, is that right Adam?).
Post by Michael Heuer
Post by Tomasz Kaye's brain
Post by Adam Tindale
Michael - excellent suggestion. FLOSS Manuals seems to have a facility
for including code easily. Has anyone tried putting ChucK code in to
see if it barfs on it?
...
I entered some ChucK code into a <pre> element. That seemed to work fine
in
Post by Tomasz Kaye's brain
the preview. Though probably needs more testing (for instance, do long
lines
Post by Tomasz Kaye's brain
inside a <pre> element automatically wrap in PDF export? my suspicion is
that they might not).
Does FLOSS manuals have an import mechanism? This would be essential
for keeping the ChucK examples/snippets separate from the
documentation itself.
For instance, in APT documentation format
http://maven.apache.org/doxia/references/apt-format.html
there is a snippet macro
http://maven.apache.org/doxia/macros/index.html#Snippet_Macro
michael
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Adam Tindale
2009-12-03 18:17:31 UTC
Permalink
Currently the examples are hard coded in. This has problems, as we all
know, but it is the best system we have for now. I am not too worried
about it. I have a vision...

Does everyone know the Max/MSP manuals? They are amazing. I have a
dream that every UGEN has a page or two to itself where all the inputs
and outputs are explained and there is a UGEN specific example in the
docs that makes it clear how the features work. I know we can do this!
I would love to get a start on it during the sprint. Even if we
documented the .sync feature of UGENs more I would be happy with that
as a start.

FLOSS manuals has started a page for us. It looks like the system for
us. They have an API for putting the manual to print and giving more
control. It is a bit young but I think we can do some feature requests
and have it grow with us.

I will start preparing the manual for upload and start roughing it on
their site.

--art
Post by Tomasz Kaye's brain
@Michael: I'm pretty confident that FLOSS Manuals doesn't have such a
dynamic code importing capability, or support for variables or dynamic
substitutions in general. So with FLOSS, code snippets would be 'hard coded'
into the documentation (I assumed that it was currently this way with the
LaTeX docs too, is that right Adam?).
Post by Tomasz Kaye's brain
Post by Adam Tindale
Michael - excellent suggestion. FLOSS Manuals seems to have a facility
for including code easily. Has anyone tried putting ChucK code in to
see if it barfs on it?
...
I entered some ChucK code into a <pre> element. That seemed to work fine in
the preview. Though probably needs more testing (for instance, do long lines
inside a <pre> element automatically wrap in PDF export? my suspicion is
that they might not).
Does FLOSS manuals have an import mechanism?  This would be essential
for keeping the ChucK examples/snippets separate from the
documentation itself.
For instance, in APT documentation format
http://maven.apache.org/doxia/references/apt-format.html
there is a snippet macro
http://maven.apache.org/doxia/macros/index.html#Snippet_Macro
  michael
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Tomasz Kaye's brain
2009-12-04 13:43:41 UTC
Permalink
@adam

Yes, agreed about the Max/MSP docs. The best i've come across for synthesis
software. Extended UGen documentation with examples would be excellent.

Looking forward to helping out with the FLOSS manuals stuff. Thanks for your
work!
Post by Adam Tindale
Currently the examples are hard coded in. This has problems, as we all
know, but it is the best system we have for now. I am not too worried
about it. I have a vision...
Does everyone know the Max/MSP manuals? They are amazing. I have a
dream that every UGEN has a page or two to itself where all the inputs
and outputs are explained and there is a UGEN specific example in the
docs that makes it clear how the features work. I know we can do this!
I would love to get a start on it during the sprint. Even if we
documented the .sync feature of UGENs more I would be happy with that
as a start.
FLOSS manuals has started a page for us. It looks like the system for
us. They have an API for putting the manual to print and giving more
control. It is a bit young but I think we can do some feature requests
and have it grow with us.
I will start preparing the manual for upload and start roughing it on
their site.
--art
Post by Tomasz Kaye's brain
@Michael: I'm pretty confident that FLOSS Manuals doesn't have such a
dynamic code importing capability, or support for variables or dynamic
substitutions in general. So with FLOSS, code snippets would be 'hard
coded'
Post by Tomasz Kaye's brain
into the documentation (I assumed that it was currently this way with the
LaTeX docs too, is that right Adam?).
Post by Michael Heuer
Post by Tomasz Kaye's brain
Post by Adam Tindale
Michael - excellent suggestion. FLOSS Manuals seems to have a
facility
Post by Tomasz Kaye's brain
Post by Michael Heuer
Post by Tomasz Kaye's brain
Post by Adam Tindale
for including code easily. Has anyone tried putting ChucK code in to
see if it barfs on it?
...
I entered some ChucK code into a <pre> element. That seemed to work
fine
Post by Tomasz Kaye's brain
Post by Michael Heuer
Post by Tomasz Kaye's brain
in
the preview. Though probably needs more testing (for instance, do long lines
inside a <pre> element automatically wrap in PDF export? my suspicion
is
Post by Tomasz Kaye's brain
Post by Michael Heuer
Post by Tomasz Kaye's brain
that they might not).
Does FLOSS manuals have an import mechanism? This would be essential
for keeping the ChucK examples/snippets separate from the
documentation itself.
For instance, in APT documentation format
http://maven.apache.org/doxia/references/apt-format.html
there is a snippet macro
http://maven.apache.org/doxia/macros/index.html#Snippet_Macro
michael
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Adam Tindale
2009-12-04 21:58:20 UTC
Permalink
Ok All,

We are moving to FLOSS manuals. Over the next week I will start to
prepare the manual for this format and start roughing it in. As this
happens I will update the list on links and processes. I will gather
some documentation about FLOSS manuals so you can read a bit or maybe
hack around on the site before the sprint.

We will run this experiment and see how it goes. Hopefully this will
prove to be a sustainable documentation practice and an easy
migration.

Thanks for all input. This has been a fruitful discussion.

a
Post by Tomasz Kaye's brain
@adam
Yes, agreed about the Max/MSP docs. The best i've come across for synthesis
software. Extended UGen documentation with examples would be excellent.
Looking forward to helping out with the FLOSS manuals stuff. Thanks for your
work!
Post by Adam Tindale
Currently the examples are hard coded in. This has problems, as we all
know, but it is the best system we have for now. I am not too worried
about it. I have a vision...
Does everyone know the Max/MSP manuals? They are amazing. I have a
dream that every UGEN has a page or two to itself where all the inputs
and outputs are explained and there is a UGEN specific example in the
docs that makes it clear how the features work. I know we can do this!
I would love to get a start on it during the sprint. Even if we
documented the .sync feature of UGENs more I would be happy with that
as a start.
FLOSS manuals has started a page for us. It looks like the system for
us. They have an API for putting the manual to print and giving more
control. It is a bit young but I think we can do some feature requests
and have it grow with us.
I will start preparing the manual for upload and start roughing it on
their site.
--art
Post by Tomasz Kaye's brain
@Michael: I'm pretty confident that FLOSS Manuals doesn't have such a
dynamic code importing capability, or support for variables or dynamic
substitutions in general. So with FLOSS, code snippets would be 'hard coded'
into the documentation (I assumed that it was currently this way with the
LaTeX docs too, is that right Adam?).
Post by Tomasz Kaye's brain
Post by Adam Tindale
Michael - excellent suggestion. FLOSS Manuals seems to have a facility
for including code easily. Has anyone tried putting ChucK code in to
see if it barfs on it?
...
I entered some ChucK code into a <pre> element. That seemed to work fine
in
the preview. Though probably needs more testing (for instance, do long
lines
inside a <pre> element automatically wrap in PDF export? my suspicion is
that they might not).
Does FLOSS manuals have an import mechanism?  This would be essential
for keeping the ChucK examples/snippets separate from the
documentation itself.
For instance, in APT documentation format
http://maven.apache.org/doxia/references/apt-format.html
there is a snippet macro
http://maven.apache.org/doxia/macros/index.html#Snippet_Macro
  michael
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-12-05 10:50:12 UTC
Permalink
Adam;

We are moving to FLOSS manuals.
Great. I know next to nothig about pdf authoring or version cotrol so I
trust in your call and commend you for the lead you are taking.

Looking forward to covering some UGens; that at least I do know something
about.

You -rightly- mentioned .sync() as a area that needs ore coverage. I hope
Kijjaz will have time to write something about that as I think he took that
further than anyone else in his one-liners.


I'd like to write something about the Blit ones as those are fun. Will Dan
himself cover LiSa? A whole volume could be written on LiSa...

Kas.
dan trueman
2009-12-05 13:26:34 UTC
Permalink
i'd be happy to write some on LiSa, but i'd also love some help,
especially from you; i clearly only use and understand a fraction of
what LiSa is useful for!

dt
Will Dan himself cover LiSa? A whole volume could be written on
LiSa...
Kassen
2009-12-05 14:01:33 UTC
Permalink
i'd be happy to write some on LiSa, but i'd also love some help, especially
from you; i clearly only use and understand a fraction of what LiSa is
useful for!
:-)

I do still have a skeleton for a LiSa-based convolution reverb lying around
somewhere. I seem to remember it's something like 25 lines (I scary stuff).
I'd like to also do a flanger and iir lowpass filter (I'm fairly certain
both can be done)...

There are two downsides to that though; I think that when taken to the
extreme people will wonder what the rest of ChucK is good for and I also
think that the manual should be accessible, not a leading cause for insanity
in computer musicians.

Mostly kidding. Ok, I do think that such examples could be useful in that
creative LiSa-usage does potentially cover a lot of important aspects of
more serious DSP without breaking the cpu-bank like a .last() to a sporked
shred to a Step would. I also think that so far the docs and examples
haven't yet covered how we can do that sort of thing in ways that would
cause some serious issues for SC or Max. We're paying for not
block-precessing (with purring cpu-fans) so we should probably show what
that's actually good for.


Yours,
Kas.
Tomasz Kaye's brain
2009-12-05 16:23:05 UTC
Permalink
I like the idea of providing some examples of ways that LiSa can be used.
For instance, I was wondering about the potential (and suitablility) of the
LiSa UGen as a way of recording and playing back automation data (for
driving params of other UGens), rather than for audio. Have any of you used
it in that way?
Post by Kassen
Post by dan trueman
i'd be happy to write some on LiSa, but i'd also love some help,
especially from you; i clearly only use and understand a fraction of what
LiSa is useful for!
:-)
I do still have a skeleton for a LiSa-based convolution reverb lying around
somewhere. I seem to remember it's something like 25 lines (I scary stuff).
I'd like to also do a flanger and iir lowpass filter (I'm fairly certain
both can be done)...
There are two downsides to that though; I think that when taken to the
extreme people will wonder what the rest of ChucK is good for and I also
think that the manual should be accessible, not a leading cause for insanity
in computer musicians.
Mostly kidding. Ok, I do think that such examples could be useful in that
creative LiSa-usage does potentially cover a lot of important aspects of
more serious DSP without breaking the cpu-bank like a .last() to a sporked
shred to a Step would. I also think that so far the docs and examples
haven't yet covered how we can do that sort of thing in ways that would
cause some serious issues for SC or Max. We're paying for not
block-precessing (with purring cpu-fans) so we should probably show what
that's actually good for.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-12-05 16:34:46 UTC
Permalink
Tomasz;
Post by Tomasz Kaye's brain
I like the idea of providing some examples of ways that LiSa can be used.
There are already quite a few in /examples/special.
Post by Tomasz Kaye's brain
For instance, I was wondering about the potential (and suitablility) of the
LiSa UGen as a way of recording and playing back automation data (for
driving params of other UGens), rather than for audio. Have any of you used
it in that way?
That does make perfect sense to me, especially if there is some specific
curve you want to use regularly that might be computationally expensive to
generate; you should be able to calculate it once, store it in a LiSa, the
re-use it many times.

Don't underestimate the combination of Envelope and the various Gen UGens
though. I think that's more powerful for this application in the general
case.
Tomasz Kaye's brain
2009-12-15 09:48:19 UTC
Permalink
What's the plan for the sprint tomorrow?

Will it first be a question of just recreating the existing manual on the
FLOSS site? If so it might be good to agree in advance on how certain
entities should be transalated across. Or a chapter can be designated as an
example, that we can use as a guide for consistency. Maybe you had thoughts
about this already Adam?

About time zones: I'm in GMT+1. The FLOSS chat works well i think, for
coordinating stuff while we're busy working on it.
Post by Kassen
Tomasz;
Post by Tomasz Kaye's brain
I like the idea of providing some examples of ways that LiSa can be used.
There are already quite a few in /examples/special.
Post by Tomasz Kaye's brain
For instance, I was wondering about the potential (and suitablility) of
the LiSa UGen as a way of recording and playing back automation data (for
driving params of other UGens), rather than for audio. Have any of you used
it in that way?
That does make perfect sense to me, especially if there is some specific
curve you want to use regularly that might be computationally expensive to
generate; you should be able to calculate it once, store it in a LiSa, the
re-use it many times.
Don't underestimate the combination of Envelope and the various Gen UGens
though. I think that's more powerful for this application in the general
case.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-12-15 16:30:07 UTC
Permalink
Post by Tomasz Kaye's brain
What's the plan for the sprint tomorrow?
I'd like to know about this as well. I reserved all of tomorrow for this
(aside from breaks for food and I'll need half a hour for a brief meeting).
I'd be happy to apply my time and expertise wherever Adam feels they are
applied best. If I don't hear anything I'm going to write about the
interaction between code and UGens and make sure the UGen reference is
complete. If there is time left I'd also get started at making sure all
UGens have a simple example dedicated to them. I'd like to make those as
simple as possible while making sure they all have at least some musical
appeal.

Those are things that I know something about and that would be fun to write
as well as useful.

I'd be happy to continue editing after the sprint (as time and inclination
permit); it's probably a more efficient usage of my time to write things
there once than to help with issues on the forum or list.

I'd also like to hear from the DEV's on this initiative. Some areas may not
warrant writeups now as they might have changes in cvs already (making it
better to postpone documentation), and as (most of?) the DEV's also teach
they should be aware of what areas lead to most questions in classroom
situations and so may warrant special attention.

Yours,
Kas.
mike clemow
2009-12-15 17:27:54 UTC
Permalink
This will be an ongoing effort, correct? I'm not sure how much time I'll
have tomorrow to help out. It's very important and I want to help with
documentation.

Mike
Post by Tomasz Kaye's brain
What's the plan for the sprint tomorrow?
I'd like to know about this as well. I reserved all of tomorrow for this
(aside from breaks for food and I'll need half a hour for a brief meeting).
I'd be happy to apply my time and expertise wherever Adam feels they are
applied best. If I don't hear anything I'm going to write about the
interaction between code and UGens and make sure the UGen reference is
complete. If there is time left I'd also get started at making sure all
UGens have a simple example dedicated to them. I'd like to make those as
simple as possible while making sure they all have at least some musical
appeal.
Those are things that I know something about and that would be fun to write
as well as useful.
I'd be happy to continue editing after the sprint (as time and inclination
permit); it's probably a more efficient usage of my time to write things
there once than to help with issues on the forum or list.
I'd also like to hear from the DEV's on this initiative. Some areas may not
warrant writeups now as they might have changes in cvs already (making it
better to postpone documentation), and as (most of?) the DEV's also teach
they should be aware of what areas lead to most questions in classroom
situations and so may warrant special attention.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
Scott Hewitt
2009-12-16 00:12:14 UTC
Permalink
hi,

I am happy to help with the documentation as well.

Whats happening?

Scott
This will be an ongoing effort, correct?  I'm not sure how much time I'll
have tomorrow to help out.  It's very important and I want to help with
documentation.
Mike
Post by Kassen
Post by Tomasz Kaye's brain
What's the plan for the sprint tomorrow?
I'd like to know about this as well. I reserved all of tomorrow for this
(aside from breaks for food and I'll need half a hour for a brief meeting).
I'd be happy to apply my time and expertise wherever Adam feels they are
applied best. If I don't hear anything I'm going to write about the
interaction between code and UGens and make sure the UGen reference is
complete. If there is time left I'd also get started at making sure all
UGens have a simple example dedicated to them. I'd like to make those as
simple as possible while making sure they all have at least some musical
appeal.
Those are things that I know something about and that would be fun to
write as well as useful.
I'd be happy to continue editing after the sprint (as time and inclination
permit); it's probably a more efficient usage of my time to write things
there once than to help with issues on the forum or list.
I'd also like to hear from the DEV's on this initiative. Some areas may
not warrant writeups now as they might have changes in cvs already (making
it better to postpone documentation), and as (most of?) the DEV's also teach
they should be aware of what areas lead to most questions in classroom
situations and so may warrant special attention.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-12-16 00:37:36 UTC
Permalink
Scott;

Whats happening?
A search for "chuck" on flossmanuals yielded no results, I think I'll start
using our own wiki tomorrow (well, today, in this time-zone) unless someting
more concrete pops up. I suggest that if we don't hear from Adam (he may be
dealing with unforseen situations) we all just create explanations and
documentation in any area we see fit to the best of our abilities. The text
is the most important thing after all; if just five people each write a
piece on one area that was previously lacking I think that should already be
a signifficant improvement.


This initiative is getting quite "distributed" right now, with Adam
apparently offline and no word from the DEV's but I don't think that need be
a huge issue as it seems like most ChucKists have their own favourite areas
and specialities anyway. After some sleep I'll keep my GMail chat as well as
wave open in case anyone needs me, I'm also up for using any chat protocol
that can be conveniently used from Linux. We could simply use the list as
well.

Yours,
Kas.
Adam Tindale
2009-12-16 00:56:01 UTC
Permalink
Hey Guys,

There is a space reserved for us at flossmanuals.net/bin/chuck

I am pulling the manual apart tonight so that it will be ready to hack
through tomorrow. I plan to be online from 9-5 MST.

For tomorrow please sign up for an account. We can start by using the
mailing list to get coordinated with our user names and then
transition to the chat function in Flossmanuals.

This is going to be fun. I think we should look at how easy it is to
collaborate and maybe work towards improving the documentation in the
UGEN section and compile a list of other issues and see how many of
them we can solve quickly.

Thanks for all the help!

--art
Post by Kassen
Scott;
Post by Scott Hewitt
Whats happening?
A search for "chuck" on flossmanuals yielded no results, I think I'll start
using our own wiki tomorrow (well, today, in this time-zone) unless someting
more concrete pops up. I suggest that if we don't hear from Adam (he may be
dealing with unforseen situations) we all just create explanations and
documentation in any area we see fit to the best of our abilities. The text
is the most important thing after all; if just five people each write a
piece on one area that was previously lacking I think that should already be
a signifficant improvement.
This initiative is getting quite "distributed" right now, with Adam
apparently offline and no word from the DEV's but I don't think that need be
a huge issue as it seems like most ChucKists have their own favourite areas
and specialities anyway. After some sleep I'll keep my GMail chat as well as
wave open in case anyone needs me, I'm also up for using any chat protocol
that can be conveniently used from Linux. We could simply use the list as
well.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Adam Tindale
2009-12-16 01:05:29 UTC
Permalink
Hey Guys,

I lied. The sandbox is here:

http://en.flossmanuals.net/bin/view/ChucK

I'll start putting up the sections later tonight.

--art
Post by Adam Tindale
Hey Guys,
There is a space reserved for us at flossmanuals.net/bin/chuck
I am pulling the manual apart tonight so that it will be ready to hack
through tomorrow. I plan to be online from 9-5 MST.
For tomorrow please sign up for an account. We can start by using the
mailing list to get coordinated with our user names and then
transition to the chat function in Flossmanuals.
This is going to be fun. I think we should look at how easy it is to
collaborate and maybe work towards improving the documentation in the
UGEN section and compile a list of other issues and see how many of
them we can solve quickly.
Thanks for all the help!
--art
Post by Kassen
Scott;
Post by Scott Hewitt
Whats happening?
A search for "chuck" on flossmanuals yielded no results, I think I'll start
using our own wiki tomorrow (well, today, in this time-zone) unless someting
more concrete pops up. I suggest that if we don't hear from Adam (he may be
dealing with unforseen situations) we all just create explanations and
documentation in any area we see fit to the best of our abilities. The text
is the most important thing after all; if just five people each write a
piece on one area that was previously lacking I think that should already be
a signifficant improvement.
This initiative is getting quite "distributed" right now, with Adam
apparently offline and no word from the DEV's but I don't think that need be
a huge issue as it seems like most ChucKists have their own favourite areas
and specialities anyway. After some sleep I'll keep my GMail chat as well as
wave open in case anyone needs me, I'm also up for using any chat protocol
that can be conveniently used from Linux. We could simply use the list as
well.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-12-16 01:26:04 UTC
Permalink
Adam;

There is a space reserved for us at flossmanuals.net/bin/chuck
Yay! much better.
Post by Adam Tindale
I am pulling the manual apart tonight so that it will be ready to hack
through tomorrow. I plan to be online from 9-5 MST.
Great!
Post by Adam Tindale
For tomorrow please sign up for an account. We can start by using the
mailing list to get coordinated with our user names and then
transition to the chat function in Flossmanuals.
I signed up. It told me my user name is "KassenOud", also subscribed to the
mailing list for this project.
Post by Adam Tindale
This is going to be fun.
I think so.
Post by Adam Tindale
I think we should look at how easy it is to
collaborate and maybe work towards improving the documentation in the
UGEN section and compile a list of other issues and see how many of
them we can solve quickly.
things I got questions about;

*MIDI out (the same as in, really, but it seems to confuse people).
*Static members of public classes as a way to share data and signals across
the whole VM
*me.yield() (this likely requires a discussion on the shreduler in some
depth, there is one in Ge's phd paper. I hope that stuff will be open for
re-use but right now it doesn't have a free/open licence).
*casting (should include a discussion on how to be safe about this).

Modest proposal;

*ending the manual with a note on how to report bugs. We have lots of those
yet I suspect too many people blame themselves for crashes (hint; if it
crashes the VM the VM is wrong).

Thanks for all the help!
Thanks for "taking point"

Kas.
Adam Tindale
2009-12-16 05:47:34 UTC
Permalink
Hi All,

I have pulled apart the manual. I have put all the bits online here:

http://creativefootwork.com/chuck/

You will find the text files of different parts of the manual and then
some images and example patches. We will need to stitch these back
together. I have made a quick start putting it on Floss manuals. I am
going to head to sleep but if anyone wants to continue where I left
off the materials are there.

Kas, great suggestions. Let's do as many of them as we can tomorrow.
There are some talk pages we can use to keep these ideas inline with
the documentation. This has been an issue in the past.

--art
Tomasz Kaye's brain
2009-12-16 08:20:48 UTC
Permalink
Great. I've made a start recreating the installation chapter. It'll be a
straight copy of the pdf version as far as possible. Username is:
TomaszKaye. Speak to you on the FLOSS chat.
Post by Adam Tindale
Hi All,
http://creativefootwork.com/chuck/
You will find the text files of different parts of the manual and then
some images and example patches. We will need to stitch these back
together. I have made a quick start putting it on Floss manuals. I am
going to head to sleep but if anyone wants to continue where I left
off the materials are there.
Kas, great suggestions. Let's do as many of them as we can tomorrow.
There are some talk pages we can use to keep these ideas inline with
the documentation. This has been an issue in the past.
--art
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Tomasz Kaye's brain
2009-12-16 10:23:48 UTC
Permalink
So far I'm finding it most efficient to paste from the source docs directly
into the FLOSS editor's html view, and manually take care of creating
paragraph tags, pre tags etc. (I found that pasting stuff into the WYSIWYG
view results in lots of html crud, mainly br tags, that then have to be
cleaned out later.)
Post by Tomasz Kaye's brain
Great. I've made a start recreating the installation chapter. It'll be a
TomaszKaye. Speak to you on the FLOSS chat.
Post by Adam Tindale
Hi All,
http://creativefootwork.com/chuck/
You will find the text files of different parts of the manual and then
some images and example patches. We will need to stitch these back
together. I have made a quick start putting it on Floss manuals. I am
going to head to sleep but if anyone wants to continue where I left
off the materials are there.
Kas, great suggestions. Let's do as many of them as we can tomorrow.
There are some talk pages we can use to keep these ideas inline with
the documentation. This has been an issue in the past.
--art
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-12-16 12:54:38 UTC
Permalink
whoops.

Couldn't sleep, took half a sleeping pill, then of course overslept.
Oh, well, for US time-zones it's still early. Will have a shower& coffee and
join the fray.

Kas.
Kassen
2009-12-17 02:35:24 UTC
Permalink
Please note that I adapted some material I had previously found in the ChucK
source, which was in turn borrowed from the STK. This may or may not affect
licensing of the manual but that was the only way in which to document the
member functions of VoicForm. Noted here for completeness and corectness,
not because I fear Perry and Gary would sue. Let's just put both the stk and
ChucK source in our list of quoted source material.

Kas.
Kassen
2009-12-17 05:17:44 UTC
Permalink
I added a section titled "extending ChucK" at the end of the manual and
moved the chapter on LicK there. This is meant to avoid obscuring the line
between what is and isn't a part of ChucK for new users, who will quite
likely already be feeling a bit overwhelmed. Similar initiatives like SMIRK
and SMULE could find a introduction there too, as could Steve's notes on
building UGens using Faust and potential future notes on dealing with the
source itself, in case somebody would feel up for that.

I'm close to calling it a night. Some notes; this is a great initiative, it
clearly works and it's a lot of fun. This is much, much preferable to Adam
going at it alone, chiefly because Adam's time, like everyone's, is limited.
It still needs a lot of work though. There are still big gaps and I noted
some spots where the explanation may be 100% correct but would also be
utterly incomprehensible to anyone without a background in math. I'd like to
suggest that this text should be readable to a teenager with a passion for
sound/music and a interest in computers who may not have a formal background
in either. I think this might lead to starting a description with a informal
introduction and perhaps a analogy that may be followed by "programmers
would call this [formal description goes here]". I'm not talking about
"dumbing things down" here, more about a clear explanation of why we are
introducing a subject to make it evident why it will be worthwhile to read
about it. Once it's clear what things are good for and how they are unlike
other things it will hopefully also be clear that it'll be useful to learn a
specialised vocabulary to talk about them.

Yours,
Kas.
Adam Tindale
2009-12-17 07:44:52 UTC
Permalink
Wise words again Kas.

I support your sentiment about making the docs clear to a teenager but
we have to stay true to the information. The nice thing about the new
system is that we can try it and if we don't like it we just roll back
the version and no harm is done.

I think we may include a section of books to read to bring someone up
to speed on the concepts. You may have noticed that instead of doing a
full tour of Windows the front of the manual gives links to a screen
tour to get started with ChucK. We could do the dsp math version of
that.

For a teenager we may just want to included more examples as well. I
would like to start putting all of the code inline in the
documentation. I am also dreaming of the day when every ugen gets an
example. Maybe also the Standard Libraries. The examples will address
your concerns about being clear about what all the language features
are good for.

I like your ideas about including Smirk. I think we also need to
include the chuck shell, and then a brief tutorial or disciption on
the miniaudicle. Maybe audicle too, though my understanding is that it
isn't used very much.

--art
Post by Kassen
I added a section titled "extending ChucK" at the end of the manual and
moved the chapter on LicK there. This is meant to avoid obscuring the line
between what is and isn't a part of ChucK for new users, who will quite
likely already be feeling a bit overwhelmed. Similar initiatives like SMIRK
and SMULE could find a introduction there too, as could Steve's notes on
building UGens using Faust and potential future notes on dealing with the
source itself, in case somebody would feel up for that.
I'm close to calling it a night. Some notes; this is a great initiative, it
clearly works and it's a lot of fun. This is much, much preferable to Adam
going at it alone, chiefly because Adam's time, like everyone's, is limited.
It still needs a lot of work though. There are still big gaps and I noted
some spots where the explanation may be 100% correct but would also be
utterly incomprehensible to anyone without a background in math. I'd like to
suggest that this text should be readable to a teenager with a passion for
sound/music and a interest in computers who may not have a formal background
in either. I think this might lead to starting a description with a informal
introduction and perhaps a analogy that may be followed by "programmers
would call this [formal description goes here]". I'm not talking about
"dumbing things down" here, more about a clear explanation of why we are
introducing a subject to make it evident why it will be worthwhile to read
about it. Once it's clear what things are good for and how they are unlike
other things it will hopefully also be clear that it'll be useful to learn a
specialised vocabulary to talk about them.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-12-17 15:24:14 UTC
Permalink
Adam;

Wise words again Kas.
Thanks.
I support your sentiment about making the docs clear to a teenager but
we have to stay true to the information. The nice thing about the new
system is that we can try it and if we don't like it we just roll back
the version and no harm is done.
Agree. I was specifically referring to the fist sentence of the section on
array;

Arrays are used represent N-dimensional ordered sets of data (of the same
type).


This is completely true, but I'd say that much of our audience will already
know what arrays are (in which case they will gloss over it as it's not new)
or they don't in which case we have a good chance of their eyes glossing
over at this. I'm not sure about other countries but in NL you only get set
theory if you pick a certain kind of math at a certain level of highschool,
which is to say nothing about "N-dimensional". Both aspects of arrays should
be in the text but I'm willing to bet I could find you a dozen people who
would be interested in making their own sounds and programs who couldn't
tell you what this sentence means while being perfectly capable of getting
up to speed with arrays in 1o minutes.

I know this line was likely put there by somebody with lots of experience in
teaching, CS and music and that I as a independent artist with just a few
workshops under his belt in teaching experience am on thin ice here but I
have serious doubts about opening a important section with a sentence like
that.
I think we may include a section of books to read to bring someone up
to speed on the concepts.
Sure, and perhaps a brief lexicon of terms like "harmonics" and
"inheritance".
You may have noticed that instead of doing a
full tour of Windows the front of the manual gives links to a screen
tour to get started with ChucK. We could do the dsp math version of
that.
I liked that. I bolted on the text by Kijjaz to cover the essentials of
Linux compilation to at least get started there on the most prominent
platforms. There is a lot of room to improve there too.
For a teenager we may just want to included more examples as well. I
would like to start putting all of the code inline in the
documentation. I am also dreaming of the day when every ugen gets an
example. Maybe also the Standard Libraries. The examples will address
your concerns about being clear about what all the language features
are good for.
Yes. And I'd like to make sure we explicitly cover what all of the Std
functions abbreviate, that should already help make them more clear.
I like your ideas about including Smirk. I think we also need to
include the chuck shell, and then a brief tutorial or disciption on
the miniaudicle. Maybe audicle too, though my understanding is that it
isn't used very much.
The problem with the Audicle is that if you'd try to use it now with a
updated manual you will be missing a lot of functionality as the included vm
is rather old. I think it'd mention it in glancing now. The mini on the
other hand will save people from the "scary" terminal which I found adds a
lot of value for a lot of people in the beginning.

Yours,
Kas.
Kassen
2009-12-17 17:47:53 UTC
Permalink
I'm sorting the UGens by type and functionality, dropping the emphasis on
ancestry (particularly the STK). This should lead to relevant UGens being
far easier to find. I am, of course, preserving the notes on where they came
from in the descriptions themselves and the STKInstruments are -of course-
in their own section as they are rather unique in function.

I already added LiSa (from the online docs) and will also add the various
Gen's. I think I'll also add CNoise, based on the reasoning that we should
be able to push the single line fix to it to cvs -and a future release- with
more ease than we'll be able to get this whole thing completely done and
looking acceptable in pdf format. Even without the fix CNoise generates
acceptable pink noise, albeit at a rather low amplitude.

All of this could be undone if there are cries of moral outrage.

As a side-note; I moved "Modulate" to the "oscillators" section as it's
basically a advanced lfo. The plain oscillators, however, have a .period(
dur ) member function that is especially useful for lfo usage. could we
consider adding this to Modulate as well?

Yours,
Kas.
Scott Hewitt
2009-12-17 18:33:49 UTC
Permalink
hi, Adam, Kas, all
Post by Kassen
Post by Adam Tindale
For a teenager we may just want to included more examples as well. I
would like to start putting all of the code inline in the
documentation. I am also dreaming of the day when every ugen gets an
example. Maybe also the Standard Libraries. The examples will address
your concerns about being clear about what all the language features
are good for.
Yes. And I'd like to make sure we explicitly cover what all of the Std
functions abbreviate, that should already help make them more clear.
Think some inline examples within the documentation would be useful in
making this a complete reference, often the example can explain much
more than the text. I keep think of some sort of integrated help
system with the mini which would have examples as well.
Post by Kassen
Post by Adam Tindale
I like your ideas about including Smirk. I think we also need to
include the chuck shell, and then a brief tutorial or disciption on
the miniaudicle. Maybe audicle too, though my understanding is that it
isn't used very much.
The problem with the Audicle is that if you'd try to use it now with a
updated manual you will be missing a lot of functionality as the included vm
is rather old. I think it'd mention it in glancing now. The mini on the
other hand will save people from the "scary" terminal which I found adds a
lot of value for a lot of people in the beginning.
Mini makes chuck much more approachable than the terminal only.

Personally I still find the ability to 'see inside the VW' really
useful with the Audicle it would be great if there was a way of
getting a copy of running shreds out of the mini as well.

scott
Kassen
2009-12-17 19:20:08 UTC
Permalink
Scott;

Think some inline examples within the documentation would be useful in
Post by Scott Hewitt
making this a complete reference, often the example can explain much
more than the text. I keep think of some sort of integrated help
system with the mini which would have examples as well.
Yes. I want to do that as well, but first I want to finish going over the
VERSIONS file and add reference sections for things that were previously
missing altogether. For example; for better or worse we have a
"StringTokenizer" data type that previously was only documented using terms
like "uh" and "very hacked" :-).

This process is becoming not unlike a archaeological expedition.

Another issue I have is that I "corrected" a whole slew of references to
"sample-synchronous" execution of shreds. Shreds aren't sample-synchronous
according to the specs (they are orders of magnitude more precise in timing)
but right now we do have a bug in shreds executing in incorrect order due to
rounding of durations to integer samps so it could be argued that that text
did accurately reflect the state the VM is now -erroneously- in. Sigh.
Post by Scott Hewitt
Personally I still find the ability to 'see inside the VW' really
useful with the Audicle it would be great if there was a way of
getting a copy of running shreds out of the mini as well.
I wonder what it would take to bolt a modern VM to the existing Audicle
code; a straight swap of the directories won't do the trick and I can't deal
with the errors that gives.

Yours,
Kas.
Robert Poor
2009-12-17 20:07:08 UTC
Permalink
Kas:

Your comments underscore the need to create a ChucK _reference
manual_, even before creating a _programmers guide_ . By definition,
most ChucK users are already programmers for whom explanations of
object oriented programming, inheritance and type casting is
superfluous. On the other hand, being able to quickly learn the
syntax for oo, inheritance and type casting is important.

Give me a decent ChucK reference manual (i.e. what the heck does the
reserved "pure" keyword do?), and I'll be happy to write a few
tutorials for beginners.

- Rob
Post by Adam Tindale
Adam;
Wise words again Kas.
Thanks.
I support your sentiment about making the docs clear to a teenager but
we have to stay true to the information. The nice thing about the new
system is that we can try it and if we don't like it we just roll back
the version and no harm is done.
Agree. I was specifically referring to the fist sentence of the
section on array;
Arrays are used represent N-dimensional ordered sets of data (of the
same type).
This is completely true, but I'd say that much of our audience will
already know what arrays are (in which case they will gloss over it
as it's not new) or they don't in which case we have a good chance
of their eyes glossing over at this. I'm not sure about other
countries but in NL you only get set theory if you pick a certain
kind of math at a certain level of highschool, which is to say
nothing about "N-dimensional". Both aspects of arrays should be in
the text but I'm willing to bet I could find you a dozen people who
would be interested in making their own sounds and programs who
couldn't tell you what this sentence means while being perfectly
capable of getting up to speed with arrays in 1o minutes.
I know this line was likely put there by somebody with lots of
experience in teaching, CS and music and that I as a independent
artist with just a few workshops under his belt in teaching
experience am on thin ice here but I have serious doubts about
opening a important section with a sentence like that.
I think we may include a section of books to read to bring someone up
to speed on the concepts.
Sure, and perhaps a brief lexicon of terms like "harmonics" and
"inheritance".
You may have noticed that instead of doing a
full tour of Windows the front of the manual gives links to a screen
tour to get started with ChucK. We could do the dsp math version of
that.
I liked that. I bolted on the text by Kijjaz to cover the essentials
of Linux compilation to at least get started there on the most
prominent platforms. There is a lot of room to improve there too.
For a teenager we may just want to included more examples as well. I
would like to start putting all of the code inline in the
documentation. I am also dreaming of the day when every ugen gets an
example. Maybe also the Standard Libraries. The examples will address
your concerns about being clear about what all the language features
are good for.
Yes. And I'd like to make sure we explicitly cover what all of the
Std functions abbreviate, that should already help make them more
clear.
I like your ideas about including Smirk. I think we also need to
include the chuck shell, and then a brief tutorial or disciption on
the miniaudicle. Maybe audicle too, though my understanding is that it
isn't used very much.
The problem with the Audicle is that if you'd try to use it now with
a updated manual you will be missing a lot of functionality as the
included vm is rather old. I think it'd mention it in glancing now.
The mini on the other hand will save people from the "scary"
terminal which I found adds a lot of value for a lot of people in
the beginning.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--:
Robert Poor
e: ***@nbt-ventures.com
p: +1 617 818 5115
b: http://blog.nbt-ventures.com
--:
This message and the information it contains are the proprietary and
confidential property of NBT Ventures and may be privileged. If you
are not the intended recipient, please do not read, copy, disclose or
distribute its contents to any party, and notify the sender immediately.
--:
Kassen
2009-12-17 20:36:40 UTC
Permalink
Rob;

Your comments underscore the need to create a ChucK _reference manual_, even
before creating a _programmers guide_ . By definition, most ChucK users are
already programmers for whom explanations of object oriented programming,
inheritance and type casting is superfluous. On the other hand, being able
to quickly learn the syntax for oo, inheritance and type casting is
important.
I respectfully disagree. I think there is a significant audience for ChucK
that knows about music, knows (something) about sound yet has never used
text as a interface to controlling these and wants to try it's hand at that.
Not everybody has the luxury of attending classes at Princeton or Stanford
and yet these people still need a place to get started.

There is no conflict here though, as the current initiative covers both
introductory tutorials and a attempt at creating a exhaustive reference to
all object types, methods, operations and keywords.
Give me a decent ChucK reference manual (i.e. what the heck does the
reserved "pure" keyword do?), and I'll be happy to write a few tutorials for
beginners.
Great! I'm in the process of writing these references and will include
"pure". I'm also looking over the tutorials that are up already as I found
some bits in there that I have serious doubts about. You can start adding
tutorials on any topic you find lacking whenever you have the time and
inclination.

"pure", to explain from memory, is a keyword to mark member functions for a
mother class that is just meant to be extended and not meant to be
instantiated on it's own (hence this function wouldn't be called). Ge once
explained that he mainly wanted to be able to write "pure fun", as in (my
example) "pure fun void cheerfulAbyss()". I can't -off hand- think of a
occasion where it will actually affect anything.

Still, it will be documented. As will the "--poop" commandline flag, which
is about as useful and as frequently used, but it exists and so it needs to
be in there. I can think of even more obscure features, but I'll have to
re-find the exact syntax.

These things aren't either/or matters, in fact we found that some files
needed to be split up because only a single user can work on a file at a
time so working on more things at the same time will help make the most of
the hands and eyes that we have.

Yours,
Kas.
Kassen
2009-12-17 23:21:26 UTC
Permalink
I threw some of the sorting of the (otherwise great) chapter on operators
about a bit.

The version I edited followed the convention of the old manual of putting
"new" and "!" (not) in the same section as operators that take only a single
input and put "-" (minus) in with those. I moved "!" to the logical
operators section, explaining that it's a exception there (in taking a
single argument), put minus in with the math as a side-note (where I feel it
belongs) and elaborated on "new" in relation to "@".

My reasoning here is that in a older version of the pdf "new" was only
mentioned as being similar to "!" in taking a single argument and this was
-at the time- extremely confusing to me as -aside from this- "new" is
nothing like "not" at all. "not" has been a elementary logical operation
since at least Frege, it's the only (non-trivial) single argument operation
in binary logic; it belongs in there.

I'm -again- open for debate here, but a sectioning based on role and
function makes a lot more sense to me than the old sectioning based on the
number of arguments.

Just pointing this out because I don't want to arbitrarily throw stuff about
without justification.

While I was at it I added "~" (bitwise invert) that wasn't previously
documented aside from Stefan's helpful note on the WiKi.

Kas.
Scott Hewitt
2009-12-17 23:32:32 UTC
Permalink
Agree regarding the sectioning,

I had always wondered what the ordering scheme was!

Grouping similar elements regarding function/role would make more
sense to me and I think would provide a more organic learning
experience.

Scott
Post by Kassen
I threw some of the sorting of the (otherwise great) chapter on operators
about a bit.
The version I edited followed the convention of the old manual of putting
"new" and "!" (not) in the same section as operators that take only a single
input and put "-" (minus) in with those. I moved "!" to the logical
operators section, explaining that it's a exception there (in taking a
single argument), put minus in with the math as a side-note (where I feel it
My reasoning here is that in a older version of the pdf "new" was only
mentioned as being similar to "!" in taking a single argument and this was
-at the time- extremely confusing to me as -aside from this- "new" is
nothing like "not" at all. "not" has been a elementary logical operation
since at least Frege, it's the only (non-trivial) single argument operation
in binary logic; it belongs in there.
I'm -again- open for debate here, but a sectioning based on role and
function makes a lot more sense to me than the old sectioning based on the
number of arguments.
Just pointing this out because I don't want to arbitrarily throw stuff about
without justification.
While I was at it I added "~" (bitwise invert) that wasn't previously
documented aside from Stefan's helpful note on the WiKi.
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2009-12-18 20:04:26 UTC
Permalink
Some more notes;

We may need some more stylistic guidelines. There are a lot of sentence
fragments (as opposed to full sentences) in the manual and considering the
subject matter and the need to frequently break up sentences to illustrate
matters in code that seems unavoidable, but I started capitalising those. I
think this improves readability.

I also need to apologise to Tomasz as I mistakenly attributed the sentence
"In its own screwed-up way, this is kind of nice because....." to him, took
it out, then send him a off-list note commenting on the usage of crude
language in official documents in a way that I -at the time- thought was
amusingly self-referential.

It turns out that line is from the original pdf. For all I know it was Ge
himself pointing out the "screwedupness" of the ChucK operator. That was
completely my mistake.

On the bright side; I cleaned up that paragraph and will document --shell
tonight in penance over my screw-up.

Kas.
mike clemow
2009-12-19 22:36:45 UTC
Permalink
This looks great! I'm going to join you all later this week.

Excitedly,
Mike
Post by Kassen
Some more notes;
We may need some more stylistic guidelines. There are a lot of sentence
fragments (as opposed to full sentences) in the manual and considering the
subject matter and the need to frequently break up sentences to illustrate
matters in code that seems unavoidable, but I started capitalising those. I
think this improves readability.
I also need to apologise to Tomasz as I mistakenly attributed the sentence
"In its own screwed-up way, this is kind of nice because....." to him, took
it out, then send him a off-list note commenting on the usage of crude
language in official documents in a way that I -at the time- thought was
amusingly self-referential.
It turns out that line is from the original pdf. For all I know it was Ge
himself pointing out the "screwedupness" of the ChucK operator. That was
completely my mistake.
On the bright side; I cleaned up that paragraph and will document --shell
tonight in penance over my screw-up.
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
Tomasz Kaye's brain
2010-01-06 09:53:58 UTC
Permalink
Could someone with publishing access link to the editable FLOSS manual from
the chuck wiki?
Post by mike clemow
This looks great! I'm going to join you all later this week.
Excitedly,
Mike
Post by Kassen
Some more notes;
We may need some more stylistic guidelines. There are a lot of sentence
fragments (as opposed to full sentences) in the manual and considering the
subject matter and the need to frequently break up sentences to illustrate
matters in code that seems unavoidable, but I started capitalising those. I
think this improves readability.
I also need to apologise to Tomasz as I mistakenly attributed the sentence
"In its own screwed-up way, this is kind of nice because....." to him, took
it out, then send him a off-list note commenting on the usage of crude
language in official documents in a way that I -at the time- thought was
amusingly self-referential.
It turns out that line is from the original pdf. For all I know it was Ge
himself pointing out the "screwedupness" of the ChucK operator. That was
completely my mistake.
On the bright side; I cleaned up that paragraph and will document --shell
tonight in penance over my screw-up.
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2010-01-06 10:06:24 UTC
Permalink
Sure. Tell me where you want it, what to say and where exactly to link to
and it'll be up within a hour or so.

Kas.
Post by Tomasz Kaye's brain
Could someone with publishing access link to the editable FLOSS manual from
the chuck wiki?
This looks great! I'm going to join you all later this week.
Post by mike clemow
Excitedly,
Mike
Post by Kassen
Some more notes;
We may need some more stylistic guidelines. There are a lot of sentence
fragments (as opposed to full sentences) in the manual and considering the
subject matter and the need to frequently break up sentences to illustrate
matters in code that seems unavoidable, but I started capitalising those. I
think this improves readability.
I also need to apologise to Tomasz as I mistakenly attributed the
sentence "In its own screwed-up way, this is kind of nice because....." to
him, took it out, then send him a off-list note commenting on the usage of
crude language in official documents in a way that I -at the time- thought
was amusingly self-referential.
It turns out that line is from the original pdf. For all I know it was Ge
himself pointing out the "screwedupness" of the ChucK operator. That was
completely my mistake.
On the bright side; I cleaned up that paragraph and will document --shell
tonight in penance over my screw-up.
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Tomasz Kaye's brain
2010-01-06 10:16:31 UTC
Permalink
hi @Kassen

I thought about having the link appear on the wiki homepage
http://wiki.cs.princeton.edu/index.php/ChucK

I imagined it either replacing or being adjacent to the
"ChucK/Manual<http://wiki.cs.princeton.edu/index.php/ChucK/Manual>(manual
errata, updates, etc)" item. If the current version of the FLOSS
manual has addressed all the things mentioned on that page, I guess it can
be retired?

I would have the link point to the 'write' page of the FLOSS system, to
encourage participation: http://en.flossmanuals.net/bin/view/ChucK/WebHome

I'd have the text link read: "ChucK Manual (User editable)"

Thanks!
Post by Kassen
Sure. Tell me where you want it, what to say and where exactly to link to
and it'll be up within a hour or so.
Kas.
Could someone with publishing access link to the editable FLOSS manual from
Post by Tomasz Kaye's brain
the chuck wiki?
This looks great! I'm going to join you all later this week.
Post by mike clemow
Excitedly,
Mike
Post by Kassen
Some more notes;
We may need some more stylistic guidelines. There are a lot of sentence
fragments (as opposed to full sentences) in the manual and considering the
subject matter and the need to frequently break up sentences to illustrate
matters in code that seems unavoidable, but I started capitalising those. I
think this improves readability.
I also need to apologise to Tomasz as I mistakenly attributed the
sentence "In its own screwed-up way, this is kind of nice because....." to
him, took it out, then send him a off-list note commenting on the usage of
crude language in official documents in a way that I -at the time- thought
was amusingly self-referential.
It turns out that line is from the original pdf. For all I know it was
Ge himself pointing out the "screwedupness" of the ChucK operator. That was
completely my mistake.
On the bright side; I cleaned up that paragraph and will document
--shell tonight in penance over my screw-up.
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2010-01-06 15:14:18 UTC
Permalink
It's up with a bit of delay.

I put it on the front page; IMHO it's both important enough for that and
already of a high enough quality to be very useful. I left the old link so
that makes it slightly cludgy, but I don't want to make destructive edits to
the front page without somebody like Adam or Ge chiming in. Aside from that
I personally I agree with your reasoning that the new system is preferable.

The one issue I have with the new system as compared to the WiKi (for people
with accounts) is that I don't think it's currently clear how new users who
find the manual unclear but don't yet have the knowledge to suggest a
addition or rewording should suggest areas for improvement. How good are our
ties with the FLOSSmanuals site? maybe it could put a "issue tracking"
feature on it's wishlist?

Kas.
Post by Tomasz Kaye's brain
I thought about having the link appear on the wiki homepage
http://wiki.cs.princeton.edu/index.php/ChucK
I imagined it either replacing or being adjacent to the "ChucK/Manual<http://wiki.cs.princeton.edu/index.php/ChucK/Manual>(manual errata, updates, etc)" item. If the current version of the FLOSS
manual has addressed all the things mentioned on that page, I guess it can
be retired?
I would have the link point to the 'write' page of the FLOSS system, to
encourage participation: http://en.flossmanuals.net/bin/view/ChucK/WebHome
I'd have the text link read: "ChucK Manual (User editable)"
Thanks!
Sure. Tell me where you want it, what to say and where exactly to link to
Post by Kassen
and it'll be up within a hour or so.
Kas.
Could someone with publishing access link to the editable FLOSS manual
from the chuck wiki?
This looks great! I'm going to join you all later this week.
Post by mike clemow
Excitedly,
Mike
Post by Kassen
Some more notes;
We may need some more stylistic guidelines. There are a lot of sentence
fragments (as opposed to full sentences) in the manual and considering the
subject matter and the need to frequently break up sentences to illustrate
matters in code that seems unavoidable, but I started capitalising those. I
think this improves readability.
I also need to apologise to Tomasz as I mistakenly attributed the
sentence "In its own screwed-up way, this is kind of nice because....." to
him, took it out, then send him a off-list note commenting on the usage of
crude language in official documents in a way that I -at the time- thought
was amusingly self-referential.
It turns out that line is from the original pdf. For all I know it was
Ge himself pointing out the "screwedupness" of the ChucK operator. That was
completely my mistake.
On the bright side; I cleaned up that paragraph and will document
--shell tonight in penance over my screw-up.
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Tomasz Kaye's brain
2010-01-07 17:19:00 UTC
Permalink
@kassen "How good are our ties with the FLOSSmanuals site? maybe it could
put a "issue tracking" feature on it's wishlist?"

Both Adam and I have spoken directly to the other Adam (confusingly) who
runs FLOSS manuals, he seems very approachable.

The FLOSS manuals does currently have a 'discussion' page for each chapter,
this might be a suitable place for people to post requests for clarification
about particular passages.

I don't know how the 'subscribe to changes' feature of FLOSS manuals works
yet, I don't know if it would pick up new things posted to a manual's
discussion pages. I'll check that out and post back. If it does, that might
work quite well (though we might need to think about how to communicate that
the 'discussion' pages of the manual are the appropriate place for posting
these kinds of thing).
Post by Kassen
It's up with a bit of delay.
I put it on the front page; IMHO it's both important enough for that and
already of a high enough quality to be very useful. I left the old link so
that makes it slightly cludgy, but I don't want to make destructive edits to
the front page without somebody like Adam or Ge chiming in. Aside from that
I personally I agree with your reasoning that the new system is preferable.
The one issue I have with the new system as compared to the WiKi (for
people with accounts) is that I don't think it's currently clear how new
users who find the manual unclear but don't yet have the knowledge to
suggest a addition or rewording should suggest areas for improvement. How
good are our ties with the FLOSSmanuals site? maybe it could put a "issue
tracking" feature on it's wishlist?
Kas.
Post by Tomasz Kaye's brain
I thought about having the link appear on the wiki homepage
http://wiki.cs.princeton.edu/index.php/ChucK
I imagined it either replacing or being adjacent to the "ChucK/Manual<http://wiki.cs.princeton.edu/index.php/ChucK/Manual>(manual errata, updates, etc)" item. If the current version of the FLOSS
manual has addressed all the things mentioned on that page, I guess it can
be retired?
I would have the link point to the 'write' page of the FLOSS system, to
http://en.flossmanuals.net/bin/view/ChucK/WebHome
I'd have the text link read: "ChucK Manual (User editable)"
Thanks!
Sure. Tell me where you want it, what to say and where exactly to link to
Post by Kassen
and it'll be up within a hour or so.
Kas.
Could someone with publishing access link to the editable FLOSS manual
from the chuck wiki?
This looks great! I'm going to join you all later this week.
Post by mike clemow
Excitedly,
Mike
Post by Kassen
Some more notes;
We may need some more stylistic guidelines. There are a lot of
sentence fragments (as opposed to full sentences) in the manual and
considering the subject matter and the need to frequently break up sentences
to illustrate matters in code that seems unavoidable, but I started
capitalising those. I think this improves readability.
I also need to apologise to Tomasz as I mistakenly attributed the
sentence "In its own screwed-up way, this is kind of nice because....." to
him, took it out, then send him a off-list note commenting on the usage of
crude language in official documents in a way that I -at the time- thought
was amusingly self-referential.
It turns out that line is from the original pdf. For all I know it was
Ge himself pointing out the "screwedupness" of the ChucK operator. That was
completely my mistake.
On the bright side; I cleaned up that paragraph and will document
--shell tonight in penance over my screw-up.
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Kassen
2010-01-07 17:45:25 UTC
Permalink
2010/1/7 Tomasz Kaye's brain
Post by Tomasz Kaye's brain
Both Adam and I have spoken directly to the other Adam (confusingly) who
runs FLOSS manuals, he seems very approachable.
That's good.
Post by Tomasz Kaye's brain
I don't know how the 'subscribe to changes' feature of FLOSS manuals works
yet, I don't know if it would pick up new things posted to a manual's
discussion pages. I'll check that out and post back. If it does, that might
work quite well (though we might need to think about how to communicate that
the 'discussion' pages of the manual are the appropriate place for posting
these kinds of thing).
I don't think it sends emails for those, actually.

What I'm envisaging is a sort of big red button marked "I have a issue with
this manual" that would result in a sort of small questionnaire that could
be filled in anonymously. Basically I want the tress-hold for filing issues
to be as low as it could possibly go. We have to remember that our target
audience here is quite likely not -yet- deeply into our little scene. They
may not have a list subscription, for all we know they didn't even yet
manage to install ChucK. I could even imagine going as far as having a
hotlink in the final pdf that would link to this feature. Right now we have
no way of getting info from people who try ChucK for a afternoon, then quit,
while that would be spectacularly valuable information.

In completely unrelated news; yesterday I realised that the "--version" flag
wasn't yet in the manual. I think this brings the total up to 32. We may
have to admit that a real "complete" manual might take a while. We do need
some more new chapters that could be written now if somebody has the time
and inspiration but I suspect a huge part of the work over the next few
months will be collecting all of the scattered bits and pieces.

Yours,
Kas.
Tomasz Kaye's brain
2010-01-11 16:51:54 UTC
Permalink
@Kassen

What I'm envisaging is a sort of big red button marked "I have a issue with
Post by Kassen
this manual" that would result in a sort of small questionnaire that could
be filled in anonymously. Basically I want the tress-hold for filing issues
to be as low as it could possibly go. We have to remember that our target
audience here is quite likely not -yet- deeply into our little scene. They
may not have a list subscription, for all we know they didn't even yet
manage to install ChucK. I could even imagine going as far as having a
hotlink in the final pdf that would link to this feature. Right now we have
no way of getting info from people who try ChucK for a afternoon, then quit,
while that would be spectacularly valuable information.
Completely agree. I'd suggest taking it up with with adam hyde from FLOSS
manuals ( ***@flossmanuals.net ). I think other open source projects with
manuals there would benefit from a feature like this too. Maybe he even
already has something in the works.
Post by Kassen
In completely unrelated news; yesterday I realised that the "--version"
flag wasn't yet in the manual. I think this brings the total up to 32. We
may have to admit that a real "complete" manual might take a while. We do
need some more new chapters that could be written now if somebody has the
time and inspiration but I suspect a huge part of the work over the next few
months will be collecting all of the scattered bits and pieces.
Yours,
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Tomasz Kaye's brain
2009-11-28 09:27:30 UTC
Permalink
Post by Adam Tindale
December 19th was an arbitrary date. How about we do the 16th since
Tomasz can make that? I would really love a git expert around. If you
guys haven't seen his tutorial on git with max, it is really
wonderful.
Yes, i can make Dec 16th. Thanks for the kid words, but I have to say
I'm far from a git expert. I wrote the tutorial because I notice that
I often feel in a good position to write instructions for beginners
when i'm only one step removed from a beginner myself! (that's also
why I'd like to contribute to the ChucK docs too). For completeness
the git tutorial mentioned can be found at:
http://www.basementhum.com/2009/02/version-control-and-maxmsp-part-1.html

If we do end up going a SCM route, it might also be worth considering
Bazaar (SCM app, like git) and Launchpad (webservice like github). I
understand that bazaar was designed with an emphasis on ease of use.
It's less feature rich than git, but should be easier to use. It also
has a cross platform graphical front end too, which might make the
transition easier for people.
Post by Adam Tindale
LaTeX has proven to be bad for many reasons. Asciidoc will be the new
build system. I'll compile relevant documentation over the next few
weeks so we can get going. The main benefit is that there is very
little markup. So, if anyone has an idea all we will need is a plain
text file or an email. It will be that simple to modify the
documentation.
Very little markup: That sounds appealing.
Post by Adam Tindale
Ours could be tutorials and code
snippets. I haven't thought about this idea for too long but I thought
I would see if it had any resonance.
Great idea. The examples directory is already really halpful, but a
place for written tutorials where we get a sense of why certain design
decisions are being made would be really valuable.
Post by Adam Tindale
I have been looking through FLOSS manuals a bit. It might be a good
place to have a scratch manual but I don't know about giving it all up
to an outside source. Two issues for me: is there a way I can easily
suck down the working version to include with the distribution and if
we migrated to the site would Ge be cool with that?
The FLOSS manuals site exports to PDF, ODT and HTML, so that may be
sufficient for grabbing a current version to include with new ChucK
distributions.

I didn't get word from Ge yet about whether he'd be okay with this.
Post by Adam Tindale
We have a wiki. I would be more interested in reinvigorating that
space for this project. Maybe we could decide at the end of the sprint
that we have outgrown it but I would like to make sure that is the
answer before committing to hard to another site.
That could also work. There are a couple of reasons I favour the FLOSS
manuals site over a regular wiki: FLOSS manuals has a concept of
maintainer, who approves new versions of chapters to 'go public', this
hopefully ensures that the canonical version of every chapter is in
good shape at all times. Also the FLOSS manuals are designed to be
easy to print. I don't know if that's so straight forward with wiki
hosted manuals.

I noticed that with the ChucK wiki you can't just sign up and use it
at the moment, you have to get an invite from a member. Which could
also raise the 'drempel' (threshold) for people wanting to contribute.

Positive things about FLOSS manuals:

It has built in chat facility so that contributors can communicate
with one another.
Chapters being edited are 'locked', avoids 'merge' complexity.
FLOSS manuals is being sponsored by Archive.org in their development
of Booki (which will be the next, better version of the site)

On the negative side about FOSS manuals:

The current site isn't always easy to navigate.
The current image manager is a pain to use.
Post by Adam Tindale
Let's spend some time picking tools and then we will move forward. We
should spend the day getting things done, not fighting with tech or
intellectual property issues.
Yes, I agree that it's better to spend a bit of time early figuring
out what makes the most sense, that having to backtrack later.
Scott Hewitt
2009-11-27 23:46:37 UTC
Permalink
Hi,

Also happy to help with any documentation sprint

Scott
Post by mike clemow
+1 for community manual.
I would love to help. Also, I'd be glad to rally any and all
Chuckists I know to book-sprint on it if need be. Whatever the
documentation solution is, please let us know how to help.
Mike
Post by Kassen
Adam;
Post by Adam Tindale
Great to see you here.
Yes, isn't it? I was enjoying Tomasz's posts elsewhere for a few years now
before running into him at Steim. It's a small world.
Post by Adam Tindale
Firstly, I would like to announce to you all that I successfully
defended my PhD this week and now that is done I will be spending more
time here collecting the great ideas that come through this list.
Both are great news! congratulations! What is your PhD on?
Post by Adam Tindale
Presently I am working on converting the manual to asciidoc, which is
a simple formatting language that produces both html and pdf copies.
This will allow us to keep the manual and the website in sync. This
has been a sore point for a long time now.
Right, this is a good point. The threshold of entry should be lower there so
everyone who would like to help can. I think most of the more senior users
have their own field of expertise that many others will know less about and
of course new users will see issues that the rest overlooks. To me the
manual is a important thing as it will be the first port of call for many
people who are considering ChucK; that's also why I felt the recent
compilation issues needed a quick fix. If we don't make a good first
impression we'll never reach world-domination.
Post by Adam Tindale
I have signed up for a github account and I would be happy to put the
chuck manual there. This will allow everyone to grab from my branch
and then I can pull changes from everyone and then commit them back to
the project. How does that sound?
Good. But then we need a intro to this. A intro to using this system aimed
at people who are not routinely using version management. Like me :-).
Post by Adam Tindale
Future. I want to have a documentation sprint. How does December 19th
look? Anyone else interested? I would be online all day giving out
tasks and helping people get into the technical parts of adding to our
document and also looking for snippets of wisdom or errata to improve
the minutia.
This sounds like a good idea, and very fitting with the inspiration Tomasz
here took from the recent Ardour sprint in Rotterdam and online.
Let me commit to covering the interaction between DSP in code and in UGens;
that's a interesting topic that I feel has so far been under-appreciated
even though it's one of the things where ChucK can really shine as compared
to other systems.
Post by Adam Tindale
I think that too much fragmentation of the project is not good. Ge has
done a great job and keeping everything together and I think that is
one of the reasons we have so many people here. It is easy to find
information (or to find out that the information doesn't exist) and it
is easy to ask questions to a list that actually responds. Having a
dev or working version of the docs is good but having it all in one
place for newbies definitely eases the transition, so I don't want to
break that "feature."
I respectfully disagree there. I do agree that Ge is doing a amazing job
that can't be praised highly enough but the information is not all in one
place. Most is in the manual but then some things are only in the examples
or even just mentioned in Ge's thesis (whole chunks of that should likely be
pasted straight into the manual). Then there are things that are only
mentioned in the list archives or on the forum or WiKi, hinted at in the old
docs on the site or even just in the VERSIONS file. I think there are also
bits that aren't documented at all; there must be as every once in a while
something pops up that has been implemented but never documented.
Of course this has so far not been a great issue as the scene is still small
enough for the people who know how to find it all to answer all questions
and this can certainly be attributed to Ge who set the tone of friendly help
to all comers (quite unlike some lists I hear about).
To pick just one thing; just the other day I was talking about the "repeat"
structure in ChucK on the Toplap list when debating the influence of syntax
on musical movements (as well as kissing as a quantitative measurement of
musical quality; it's a wonderful list). Even I myself can't remember where
I found that one (might be Ge's thesis?). The manual mentions it's
existence, but not how it works;
repeat(3)
  {
  <<<"this will be printed three times">>>;
  }
...a wonderful device, it can be used immediately even if you have just seen
it once so it's a great introduction to loops, it's simplicity makes it
great for casual impulsive livecoding with a drink at hand, but don't ask me
where it's documented.
Post by Adam Tindale
These are my current thoughts. What do you think?
Yes, yes, yes &yes. Great ideas, it's good to see you back on the case and
we'll do this. I'm in and I hope we'll see a strong turnout of people
writing, suggesting and proof-reading.
After this I'd like a sprint on the /examples/ dir. There are some bits in
there that I find questionable. We can debate style (some structures have
become out-dated) but I feel they should all run without errors or warnings
(this is not currently the case) and there are some otherwise dubious bits
here and there. I think I kept some notes on those somewhere but might have
misplaced them.
Great initiative!
Kas.
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
--
http://michaelclemow.com
http://semiotech.org
_______________________________________________
chuck-users mailing list
https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
Loading...