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

Adam Tindale adamtindale at hotmail.com
Wed Dec 2 01:25:58 EST 2009


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 <wittlist at googlemail.com> 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
> <tomasz.brain at gmail.com> wrote:
>> Good points Adam. A couple of related comments:
>>
>> On Sat, Nov 28, 2009 at 8:22 PM, Adam Tindale <adamtindale at hotmail.com> 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 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
>
>


More information about the chuck-users mailing list