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

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