Re: [chuck-users] FLOSS (user editable) manual for ChucK

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 wrote:

@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).

2009/11/28 Kassen :

...

Adam;

...

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 :-)

...

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 :-)

...

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.

...

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 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 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.

...

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 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 chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users

_______________________________________________ chuck-users mailing list chuck-users@lists.cs.princeton.edu https://lists.cs.princeton.edu/mailman/listinfo/chuck-users