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

Ok All, We are moving to FLOSS manuals. Over the next week I will start to prepare the manual for this format and start roughing it in. As this happens I will update the list on links and processes. I will gather some documentation about FLOSS manuals so you can read a bit or maybe hack around on the site before the sprint. We will run this experiment and see how it goes. Hopefully this will prove to be a sustainable documentation practice and an easy migration. Thanks for all input. This has been a fruitful discussion. a 2009/12/4 Tomasz Kaye's brain :

@adam

Yes, agreed about the Max/MSP docs. The best i've come across for synthesis software. Extended UGen documentation with examples would be excellent.

Looking forward to helping out with the FLOSS manuals stuff. Thanks for your work!

On Thu, Dec 3, 2009 at 7:17 PM, Adam Tindale wrote:

...

Currently the examples are hard coded in. This has problems, as we all know, but it is the best system we have for now. I am not too worried about it. I have a vision...

Does everyone know the Max/MSP manuals? They are amazing. I have a dream that every UGEN has a page or two to itself where all the inputs and outputs are explained and there is a UGEN specific example in the docs that makes it clear how the features work. I know we can do this! I would love to get a start on it during the sprint. Even if we documented the .sync feature of UGENs more I would be happy with that as a start.

FLOSS manuals has started a page for us. It looks like the system for us. They have an API for putting the manual to print and giving more control. It is a bit young but I think we can do some feature requests and have it grow with us.

I will start preparing the manual for upload and start roughing it on their site.

--art

2009/12/2 Tomasz Kaye's brain :

...

@Michael: I'm pretty confident that FLOSS Manuals doesn't have such a dynamic code importing capability, or support for variables or dynamic substitutions in general. So with FLOSS, code snippets would be 'hard coded' into the documentation (I assumed that it was currently this way with the LaTeX docs too, is that right Adam?).

On Wed, Dec 2, 2009 at 4:43 PM, Michael Heuer wrote:

...

Tomasz Kaye's brain :

...

...

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 entered some ChucK code into a <pre> element. That seemed to work fine in the preview. Though probably needs more testing (for instance, do long lines inside a <pre> element automatically wrap in PDF export? my suspicion is that they might not).

Does FLOSS manuals have an import mechanism?  This would be essential for keeping the ChucK examples/snippets separate from the documentation itself.

For instance, in APT documentation format

http://maven.apache.org/doxia/references/apt-format.html

there is a snippet macro

http://maven.apache.org/doxia/macros/index.html#Snippet_Macro

  michael _______________________________________________ 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

_______________________________________________ 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