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

[Adam Tindale]

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
<tomasz.brain at gmail.com> 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 <signal.automatique at gmail.com>:
>> 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 at lists.cs.princeton.edu
>> https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
>>
>>
> _______________________________________________
> chuck-users mailing list
> chuck-users at lists.cs.princeton.edu
> https://lists.cs.princeton.edu/mailman/listinfo/chuck-users
>