Merge pull request #935 from jamshark70/topic/hjhDocFixes

Documentation: Escape char in string literals, and thisProcess.nowExecutingPath

HelpSource/Classes/Process.schelp

@@ -16,6 +16,18 @@ Get or set tail call optimization. The default is on. Setting this to code::fals
 
 instanceMethods::
 
+method::nowExecutingPath
+
+Usage: code::thisProcess.nowExecutingPath::
+
+Returns the full path to the file containing the code that is currently executing emphasis::interactively:: in the interpreter. Usually this is the current document. If the code block executes another file on disk, using link::Classes/String#-load:: or link::Classes/String#-loadPaths::, teletype::nowExecutingPath:: will be the location of the the executed file.
+
+teletype::nowExecutingPath:: is valid only for interactive code, i.e., code files with a teletype::.scd:: extension. It does not apply to class definitions (teletype::.sc::). For that, use code::thisMethod.filenameSymbol:: or code::this.class.filenameSymbol::.
+
+This method is supported in the SuperCollider IDE, the Macintosh-only SuperCollider.app, and the scel (SuperCollider-Emacs-Lisp) environment. In other editor environments, it will return code::nil::.
+
+WARNING:: teletype::nowExecutingPath:: has a corresponding setter method, teletype::nowExecutingPath_::, for internal use only by the interpreter. Do not call the setter method!::
+
 method::startup
 
 called after the class library has been compiled. Override this in class link::Classes/Main:: to do whatever you want.

HelpSource/Classes/String.schelp

@@ -17,6 +17,8 @@ y = "this is a\n"
     "string";
 ::
 
+A backslash is the escape character. See link::Reference/Literals#Escape character::.
+
 CLASSMETHODS::
 
 private::initClass

HelpSource/Reference/Literals.schelp

@@ -106,16 +106,17 @@ $B
 $C
 ::
 
-Tab, linefeed, carriage return, and backslash are preceded by a backslash:
+Tab, linefeed, carriage return, and backslash are preceded by a backslash. See link::#Escape character:: below.
 code::
 $\t
 $\n
 $\r
 $\\
 ::
 
-section::Symbols
+section::Symbols and Strings
 
+subsection::Symbols
 A symbol is written as a string enclosed in single quotes.
 examples of symbols:
 code::
@@ -134,7 +135,7 @@ code::
 \BigSwiftyAndAssoc
 ::
 
-section::Strings
+subsection::Strings
 
 Strings are written in double quotes:
 code::
@@ -155,12 +156,23 @@ string.
 "
 ::
 
+subsection::Escape character
+
+As in C and Java, a backslash, \, is the emphasis::escape character::. Escaping has two main purposes:
+
+list::
+## To insert non-printing characters into a string: teletype::\n:: for newline, teletype::\t:: for tab, teletype::\l:: for linefeed, teletype::\r:: for carriage return. (This usage is valid only for Strings, not Symbols.)
+## To allow a string or symbol delimiter to be included in the contents. That is, for strings, normally double-quote marks indicate the beginning and ending of the string literal. To put a double-quote in the middle of the string, the normal meaning of double-quote should be suspended -- "escaped" -- as in code::"He repeated, \"Madam, I'm Adam,\" only this time he had said it backward."::
+::
+
+In all cases, the \ as an escape character does not appear in the string or symbol. This is a frequent source of confusion for Windows file paths, e.g., code::"C:\Users\Somebody\SuperCollider":: translates into teletype::C:UsersSomebodySuperCollider::. Backslashes that should appear need to be escaped themselves: code::"C:\\Users\\Somebody\\SuperCollider"::. (Note, however, that it is preferable to write file paths using forward slashes, regardless of platform, as in Java: code::"C:/Users/Somebody/SuperCollider"::.)
+
 section::Identifiers
 
 Names of methods and variables begin with a lower case alphabetic character, followed by zero or more
-alphanumeric characters:
+alphanumeric characters. An underscore is also valid in an identifier.
 code::
-var abc, z123, func;
+var abc, z123, trigger_func;
 ::
 
 section::Class Names