HelpSource/Reference/Quark.schelp

   1 title:: Quark
   2 summary:: Quark file format
   3 categories:: Quarks
   4 related:: Guides/Quarks, Classes/Quark
   5
   6 A Quark is a package of SC classes, helpfiles, C++ source for UGens and other SC code. A Quark object is created from
   7 the quark file found in {Application Support}/quarks/DIRECTORY. These Quark objects are mostly used just by the Quarks
   8 class, and you usually don't need to deal with them at all. But to publish a quark, you do need to make the quark file.
   9
  10 section:: Format of the .quark File
  11
  12 This quarkfile is written in sc code, and should contain a dictionary with basic information about the package.
  13
  14 code::
  15 (
  16 // required:
  17     \name:           "theName",
  18     \path:           "foldername", // almost always the same as the quark name
  19     \summary:        "Human readable summary",
  20     \author:         "My Name",
  21
  22 // optional:
  23     \version:        1.0, // must be a float
  24     \organization:   "My Organization",
  25     \country:        "My Country",
  26     \since:          "2004",
  27     \helpdoc:        "Classes/MyClass",
  28     \ext_dependancy: "Information on additional software needed to run this quark properly",
  29     \url:            "http://www.strangeQuark.de",
  30
  31 // If the quark depends on other quarks, you can specify it as a list containing:
  32 // (1) strings (just the quark name)
  33     \dependencies:   "nameOfDependantQuark"
  34 // (2) key->value pairs (name->version)
  35 //  \dependencies:   [("nameOfDependantQuark" -> 1.0)]
  36 // or (3) arrays with info in this order: [name, version, repositoryBaseUrl]
  37 //  \dependencies:   [["nameOfDependantQuark", 1.0, "https://svn.weirdserver.be/trunk/weirdquarks"]]
  38
  39 )
  40 ::
  41
  42 Of particular importance for the Quarks interface class is the PATH. This is the path relative to the quark directory.
  43 In most cases this is simply the name of the quark and also the name of the folder. However, you may wish to create a
  44 parent folder and then keep several quarks inside that, in which case your path would be: parentfolder/quarkname
  45
  46 It may even be possible to nest quarks inside of quarks (a kind of aggregate package), though a better way to do that
  47 would be to define an empty quark (the aggregate) and specify the other sub quarks as dependencies.
  48
  49 The value of code::\helpdoc:: is a help path relative to an included teletype::HelpSource:: folder.
  50 It is used as the main help file for the quark. (See link::Classes/Quark#-openHelpFile:: )
  51 For example, if the quark contains teletype::HelpSource/Reference/MyQuark.schelp:: one would use:
  52 code::
  53     \helpdoc: "Reference/MyQuark"
  54 ::
  55
  56 note:: Please test that you don't have any syntax errors in your quark file before commiting it.::