Documentation project

SCDoc is now part of the main supercollider git repo

= Work assignments =

Todo

 * /Extending and Customizing SC/ (only documentation of standalone applications is missing)
 * /Extending and Customizing SC/Quarks/
 * /GUI/Cocoa-GUI (some files were done, please check bellow)
 * /GUI/guicrucial
 * Many Pattern classes are not documented.

UGens missing old help file:
 * InBus
 * XIn
 * XInFeedback
 * ScopeOut
 * APF
 * LagControl
 * PauseSelfWhenDone
 * TrigControl

Choose a directory from the old help system (above) to convert and write it up here so we don't get duplicate work:

work in progress

 * AudioControl ugen - Josh Parmenter
 * GUI/*.html (not sub folders) Saratruska
 * FlowView.html
 * SimpleController.html
 * GUI/Main-GUI - Jakob Leben
 * Dialog.html
 * HLayoutView.html
 * Knob.html
 * MovieView.html
 * Pen.html
 * ScopeView.html
 * ScrollView.html
 * SoundFileView.html
 * Stethoscope.html
 * StubTemplate.html
 * TabletView.html
 * VLayoutView.html

done

 * /Extending and Customizing SC/ - Tim Blechmann (exceptions: documentation of old help system, crossplatform, publishing code)
 * /3vs2 - Saratruska
 * /Ugens - Grirgz (converted from http://sced.berlios.de/reference/Reference.tar.bz2)
 * /Core - miguel Negrão
 * /Geometry - Grirgz
 * /UGens/Algebraic - Saratruska
 * /UGens/Analysis - Saratruska
 * /UGens/Chaos - Saratruska
 * /Platform - Jonatan Liljedahl
 * /Language - Jonatan Liljedahl
 * /Ugens/UGen.html - Jonatan
 * Ugens not in docbook conversion - Saratruska
 * /Other topics - Jonatan
 * /Server-Architecture - Jonatan Liljedahl
 * /Linux - Jonatan
 * /Scheduling - redFrik
 * /Collections - redFrik
 * /Control - redFrik
 * /OSX - redFrik
 * /Streams-Patterns-Events - redFrik
 * /Tutorials - redFrik
 * /Files - redFrik
 * /Libraries/JITLib - redFrik
 * /BinaryOps (moved to operator overview) - Jonatan
 * /UnaryOps (moved to operator overview) - Jonatan
 * /Math/Integer - Jonatan
 * /Math/Float - Jonatan
 * /Math/Magnitude - Jonatan
 * /Math/Number - Jonatan
 * /Math/Polar - Jonatan* /GUI/EZ-GUI Saratruska
 * /Math/SimpleNumber - LFSaw
 * /Math/Complex - LFSaw
 * /GUI/GUI-Tools Saratruska
 * /GUI/Cocoa/ -> files alphabetically from CocoaMenuItem.html to SCFreqScopeWindow.html (ls -l) Saratruska
 * Hilbert ugen - Josh Parmenter
 * HilbertFIR ugen - Josh Parmenter

Also, please check the sf git repo for already added files...

Ugens in need of updating from old doc

 * Line // missing "see also" and examples
 * LocalOut LocalIn // missing "see also: LocalBuf
 * Mix // some sentences missing in the examples (or in the fill method )
 * MouseX // missing one example
 * MouseY // missing one example
 * MostChange // in examples: why it says it doesnt work ? missing a // before a comment. missing a comment
 * NumRunningSynths // the ir method is specified but empty (same in old doc)
 * OffsetOut // last example seem to be a "dont do that" example, but nothing tell it
 * Osc // the Note about wavetable has disapeared
 * Out // missing the sentence "When using an array....". missing examples
 * PV_ConformalMap // examples differs (merge them ?)
 * PanAz // "pos" description differs a bit
 * PauseSelf // need to update the example to not using s.sendMsg
 * PingPong // old doc says "between a number of output" while the new says "two outputs" i dont know which one is correct
 * PinkNoise // somes examples are missing from new doc
 * RHPF // miss two comments in the example
 * RLPF // miss two comments in the example
 * RandID // miss "see also randomSeed"
 * ReplaceOut // "See Synth and Order-of-execution" are not links
 * SampleDur // miss examples
 * SampleRate // examples differs
 * Saw // miss "control rate" precision on the freq argument
 * SendTrig // miss "For sending an array of values, or an arbitrary reply command, see SendReply"
 * Slew // miss "//" at the beginning of comment in the example
 * TExpRand // miss a period in the sentence before "lo and hi"
 * Trig // miss an example
 * Trig1 // miss "//" before comments
 * VOsc // "[*allocConsecutive]" is not a link. miss "Note that since VOsc uses fractional buffer numbers..."
 * VOsc3 // "[*allocConsecutive]" is not a link. miss "Note that since VOsc uses fractional buffer numbers...". Some VOsc should be replaced by VOsc3
 * VarSaw // examples differs
 * WhiteNoise // miss some examples

Ugens not found in old doc ugen overview

 * Logistic
 * MidEQ
 * MultiTap
 * NumAudioBuses
 * NumBuffers
 * NumControlBuses
 * NumInputBuses
 * NumOutputBuses
 * PMOsc
 * PSinGrain
 * PV_Add
 * PV_BinScramble
 * PV_BinShift
 * PV_BinWipe
 * PV_BrickWall
 * PV_CopyPhase
 * PV_Diffuser
 * PV_HainsworthFoote
 * PV_LocalMax
 * PV_MagAbove
 * PV_MagBelow
 * PV_MagClip
 * PV_MagFreeze
 * PV_MagMul
 * PV_MagNoise
 * PV_MagShift
 * PV_MagSmear
 * PV_MagSquared
 * PV_Max
 * PV_Min
 * PV_Mul
 * PV_PhaseShift
 * PV_PhaseShift270
 * PV_PhaseShift90
 * PV_RandComb
 * PV_RandWipe
 * PV_RectComb
 * PV_RectComb2
 * PeakFollower
 * RadiansPerSample
 * Ramp
 * RunningMax
 * RunningMin
 * Schmidt
 * SetResetFF
 * Silent
 * SubsampleOffset
 * TDelay
 * TPulse
 * Tap
 * ToggleFF
 * Wrap

= Old notes of doc project = The help-system is a bit of a mess and several improvements are wanted.


 * Some stuff should be more or less autogenerated for a consistent reference doc:
 * class reference with descriptions of methods and their arguments
 * Some stuff should be fully autogenerated:
 * class inheritance tree
 * class index by alphabetical order
 * ugens (and other classes) overview grouped by categories
 * method index
 * We need more tutorials and guides
 * You should never have to edit HTML directly
 * Tags/keywords/categories for both class-reference and other documentation
 * can be used for better search and navigation, generated overviews/indexes, etc.
 * by using tags to group files we could have all class-help-files in a flat directory structure and present many differently organized overviews. (all classes by alphabetical order, only ugens, ugens by category, inheritance tree, etc..)

Hand-written parts
For the hand-written parts, suggestions include:
 * a wiki-like plain text format (like Markdown or reStructuredText)
 * easier to write, harder to extract metadata into SC
 * sc-code (Events/Dictionaries and Arrays with strings)
 * harder to write, easier to access from SC

Some Background and Discussion
Proposal from last Symposium: http://www.listarc.bham.ac.uk/lists/sc-dev/msg09336.html

recent discussion: http://www.listarc.bham.ac.uk/lists/sc-dev/msg18596.html

Desirable Features of a New System

 * authoring format human readable and writable
 * convertible to a wide variety of other formats (html, pdf, plain text...)
 * including for example variant html based on target viewer
 * ideally be structured enough to allow for aspects of the documentation to be queried and manipulated. Some possible examples:
 * Auto-generate a file with the harvested documentation texts of all implementations of the method play.
 * alt-click on a method name and have its method doc appear in a floating window above your code window
 * jump directly to the location of a method, section, example, etc. in a given help file, not just from an anchor link, but from anywhere in the client or in your code that you want to.
 * Auto-generate a document which contains every code example which uses a particular method or class
 * allow clients to reformat the doc as needed (note that as it stands different clients have different needs already) without requiring any dependencies
 * replace doc on overridden methods
 * if a user asks for help on, say, Array:sort they can be re-directed to the SequenceableCollection helpfile where sort is documented

Class reference
One suggestion is to make a clear distinction of a consistent class reference and other documentation. The class reference would then only contain descriptions of the class, the methods and their arguments. There could be links to separate guides, tutorials, examples, etc..

It would be powerful to have access to this reference from within sclang, for future IDE integration and stuff like that.

The class reference would then be harvested from the actual source-code to get method names and arguments and their default values, combined with human-input in the form of:
 * in-source doc-comments (easier to write, but needs parsing by tool)
 * or in-source or external doc in the form of real sc code (harder to write, but needs no parsing)
 * or wiki-like plain text template in separate file (needs parsing back into sc)