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

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 On Tue, Dec 1, 2009 at 7:15 PM, Scott Hewitt wrote:

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

...

Good points Adam. A couple of related comments:

On Sat, Nov 28, 2009 at 8:22 PM, Adam Tindale wrote:

...

Upon further investigation there are a few other downsides to FLOSS manuals:  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 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