HelpSource/Classes/Quark.schelp

   1 class:: Quark
   2 summary:: Package of SC classes and extensions
   3 categories:: Quarks
   4 related:: Guides/UsingQuarks, Classes/Quarks
   5
   6 description::
   7
   8 A Quark is a package of SC classes, helpfiles and other SC code.
   9
  10 A Quark object is created from the quark file found at code::Quarks.local.path +/+ "DIRECTORY" +/+ nameOfQuark ++ ".quark"::.
  11 These Quark objects are mostly used just by the link::Classes/Quarks:: 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.
  12
  13 subsection:: Format of the .quark file
  14
  15 This quarkfile is written in sc code, and should contain a dictionary with basic information about the package.
  16
  17 code::
  18 (
  19 // required:
  20     \name:           "theName",
  21     \path:           "foldername", // almost always the same as the quark name
  22     \summary:        "Human readable summary",
  23     \author:         "My Name",
  24
  25 // optional:
  26     \version:        1.0, // must be a float
  27     \organization:   "My Organization",
  28     \country:        "My Country",
  29     \since:          "2004",
  30     \schelp:         "Classes/MyClass",
  31     \ext_dependancy: "Information on additional software needed to run this quark properly",
  32     \url:            "http://www.strangeQuark.de",
  33
  34 // If the quark depends on other quarks, you can specify it as a list containing:
  35 // (1) strings (just the quark name)
  36     \dependencies:   "nameOfDependantQuark"
  37 // (2) key->value pairs (name->version)
  38 //  \dependencies:   [("nameOfDependantQuark" -> 1.0)]
  39 // or (3) arrays with info in this order: [name, version, repositoryBaseUrl]
  40 //  \dependencies:   [["nameOfDependantQuark", 1.0, "https://svn.weirdserver.be/trunk/weirdquarks"]]
  41
  42 )
  43 ::
  44
  45 Of particular importance for the Quarks interface class is the PATH. This is the path relative to the quark directory.
  46 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 parent folder and then keep several quarks inside that, in which case your path would be: parentfolder/quarkname
  47
  48 It may even be possible to nest quarks inside of quarks (a kind of aggregate package), though a better way to do that would be to define an empty quark (the aggregate) and specify the other sub quarks as dependencies.
  49
  50 The value of code::\schelp:: optionally sets the main help file for the quark. It is a help path relative to an included teletype::HelpSource:: folder.
  51 For example, if the quark contains teletype::HelpSource/Reference/MyQuark.schelp:: one could use:
  52 code::
  53     \schelp: "Reference/MyQuark"
  54 ::
  55 It is used by link::#-openHelpFile::. If no code::\schelp:: is given, it will open the category browser showing all helpfiles for the quark.
  56
  57 note::
  58 The old help system (sc version 3.4) used code::\helpdoc::, and the new help system (link::Classes/SCDoc::) uses code::\schelp:: instead to be able to support both old and new helpfiles during the transition to the new help system.
  59 ::
  60
  61 warning:: Please test that you don't have any syntax errors in your quark file before commiting it.::
  62
  63 classmethods::
  64 method:: find
  65 Return the Quark object with specified name, if found.
  66
  67 instancemethods::
  68 method:: name
  69 The name of the quark.
  70 method:: summary
  71 The summary of the quark.
  72 method:: version
  73 The version of the quark.
  74 method:: author
  75 The author of the quark.
  76 method:: path
  77 The path of the quark.
  78 method:: info
  79 The whole info blob as given in the .quark file.
  80 method:: openHelpFile
  81 Open the main helpfile for this quark as given by the code::\schelp:: key in the directory file,
  82 or the category browser page showing all helpfiles for this quark if no main helpfile was specified.
  83 This method falls back to opening the old help as given by code::\helpdoc:: if above fails.
  84