HelpSource/Guides/More-On-Getting-Help.schelp

   1 title:: More on Getting Help
   2 summary:: How to find more help
   3 categories:: Help
   4 related:: Search, Browse, Help
   5
   6 note:: This help file uses the key commands for OS X; on other systems, please substitute the Shortcuts as necessary ::
   7
   8 Listed below are a few techniques for tracking down documentation and functionality. Note: If some of the terms used below (e.g. class, method, inheritance, etc.) are unclear to you, you may wish to read the link::Guides/Glossary:: and link::Browse#Language:: helpfiles for detail on some of these concepts. Reading a general tutorial on Object Oriented Programming at some point could also be useful, as could reading a FAQ, etc. about Smalltalk. Smalltalk is the general purpose OOP language upon which the the design of the SuperCollider language is based. Its syntax is different than SC's, but conceptually it has much in common.
   9
  10 NB: Be sure to check out the Further Info section at the bottom of this page.
  11
  12 section:: Basics
  13
  14 As you've probably already learned selecting any text and pressing Cmd-d will open the corresponding helpfile. Usually helpfiles are either concept related, or document particular classes. In the SC language classes begin with capital letters. Try Cmd-d on the following (double click on the first word; the stuff after the two slashes is a comment):
  15 code::
  16 Class // this is a class
  17 ::
  18 Methods begin with lower-case letters, as do many other things in the language.
  19 code::
  20 play // Cmd-d on this will open a helpfile detailing different implementations of this method
  21 ::
  22
  23 In addition there are a many helpfiles which explain important concepts. See the link::Browse##category browser:: and the link::Search##search page::.
  24
  25 Much documentation contains hypertext links to other helpfiles. Click the link to open the corresponding helpfile.
  26
  27 Note that many helpful methods print information to the 'post window'. Unless you have explicitly changed it (see the Window menu) this is the window which opened when you launched. Pressing Cmd-\ will bring the current post window to the front.
  28
  29 section:: Tracking Down Information
  30
  31 Executing the following
  32 code::
  33 HelpBrowser.openBrowsePage;
  34 ::
  35 will open a the "help browser" page which lists all helpfiles in thematic categories. (Equivalently, press Shift-Cmd-D)
  36
  37 The link::Browse#Undocumented classes:: contains a list of all classes which have no helpfiles. This can be a good place to start looking for functionality which may already be implemented. Even if a class has no written helpfile, it will have an automatically generated stub listing the methods and their arguments, and also a help template for writing a real helpfile.
  38
  39 Looking in class definitions (select any class and press Cmd-j to open its class definition file) can help you to figure out what undocumented methods do.
  40 code::
  41 Array // Try Cmd-j on this
  42 ::
  43 Since many methods use other classes, you may need to continue your search in other class definitions or helpfiles.
  44
  45 Executing the method dumpInterface on any class will list its class and instance methods and their arguments (if any).
  46 code::
  47 Array.dumpInterface; // Look at the post window (the one that opened when you started SC)
  48 ::
  49 Note that since the SuperCollider language is object-oriented many classes inherit methods from farther up the class hierarchy. (The many subclasses of Collection are a good example of this. See the Collections overview for more detail.) It would be impractical and redundant to document every inherited method that a class responds to, so it is important to be able to track down documentation and method definitions.
  50
  51 The method dumpFullInterface applied to any Class will list all class and instance methods that a class responds to, sorted by the class in which they are implemented. This will include inherited methods. Methods overidden in a subclass are listed under the subclass.
  52 code::
  53 Array.dumpFullInterface;
  54 ::
  55 This can be a lot of information, so dumpAllMethods or class.dumpAllMethods will show only instance and class methods respectively.
  56 code::
  57 Array.class.dumpAllMethods; // Only class methods that this responds to (including inherited ones)
  58 Array.dumpAllMethods;           // Only instance methods (including inherited ones)
  59 ::
  60 There is also a graphical Class browser which will show all methods, arguments, subclasses, instance variables and class variables. Using the browser's buttons you can easily navigate to the class' superclass, subclasses, class source, method source, helpfile (if there is one), check references or implementation of methods, or even open a web browser to view the corresponding entry in the online SVN repository. (Note that the web repository is a backup often a day or two behind the status of what is available to developers.)
  61 code::
  62 SequenceableCollection.browse;
  63 ::
  64 Selecting any method and pressing Cmd-y will open a window with a list of all the classes that implement that method. (See the link::Guides/Polymorphism:: helpfile for detail on why different classes might implement methods with the same name.)
  65 code::
  66 select // try it on this method
  67 ::
  68 Similarly, selecting any text and typing shift-cmd-y will open a window showing all references to the selected text, i.e. each place it is used within the class library. (This will not find methods calls compiled with special byte codes like 'value'.)
  69 code::
  70 // try it on these
  71 asStream
  72 SCWindow
  73 ::
  74 In the resulting window selecting any class and method and pressing Cmd-j will take you to that method definition in that class definition. For example try selecting Pattern-select in the window resulting from the previous example. Note that SC supports defining methods in separate files, so a class' methods may be defined in more than one place. If you try Cmd-j on the following you will see that it will open a file called dumpFullInterface.sc rather than one called Class.sc (its main class definition file). The + Class {.... syntax indicates that these are additional methods.
  75 code::
  76 Class-dumpFullInterface
  77 ::
  78 If you know that a class responds to a particular message, you can use findRespondingMethod to find out which class it inherits the corresponding method from.
  79 code::
  80 Array.findRespondingMethodFor('select'); // you can Cmd-j on the result in the post window
  81 ::
  82 Similarly, helpFileForMethod will open the helpfile of the class in which the responding method is defined (if the helpfile exists). Note that this does not guarantee that the method is documented therein. As noted above, some documentation is incomplete, and some methods are 'private' or not intended for general use.
  83 code::
  84 Array.helpFileForMethod('select'); // this will open the Collection helpfile; scroll down for select
  85 ::
  86 In general poking around can be a good way to learn about how things work. See link::Guides/Internal-Snooping:: for more advanced information about how to look 'under the hood.'
  87
  88 section:: For Further Info
  89
  90 http://supercollider.sourceforge.net/
  91
  92 A good starting place for figuring out how to do something are the numerous files in the Examples folder. The SuperCollider swiki is another good source of tips, examples, and information:
  93
  94 http://supercollider.sourceforge.net/wiki
  95
  96 Further help can be obtained by subscribing and sending questions to the sc-users mailing list:
  97
  98 http://www.beast.bham.ac.uk/research/sc_mailing_lists.shtml
  99
 100 An archive of the list can be searched from this page:
 101
 102 http://www.listarc.bham.ac.uk/lists/sc-users/search/
 103
 104 Requests for documentation of undocumented methods or classes, as well as reports of errata, omissions, etc. in helpfiles can be sent to the user's list above. Bugs or Feature Requests can be filed here:
 105
 106 https://sourceforge.net/tracker2/?group_id=54622
 107