HelpFile2

utility class to create a help file for a class

Inherits from:: Object : AbstractFunction : Stream : IOStream : UnixFILE : File

This class can be used to create helpfiles for SuperCollider classes. You can create a helpfile fully from the SuperCollider language. The only thing you may want to do afterwards is rearrange the order of the method descriptions. This class creates a readable HTML, so it will be easy to do so.

Creation / Class Methods

new(name,pathName)

Create an instance of HelpFile2, with the name (should be the classname) and path pathName. If no path is given, it will create one in the current working directory and give it the classname and the HTML extension.

Accessing Instance and Class Variables

createDoc(varname)

Creates a document which contains a blank template to fill out with descriptions and execute to create the helpfile. varname should be the variable name you gave to the HelpFile2 instance (e.g. "~hf", like in the example below)

classname_(name)

sets the classname for the current helpfile. This autogenerates the instanceMethods and classMethods.

classname

the classname for the current helpfile.

shortDescription

shortDescription_

Set the short (header) description for the helpfile.

longDescription

longDescription_

Set the long prose description for the helpfile.

addDescription(key,desc,type,key2)

Add a description for an instance or class method, or one of their arguments

key

The name of the method

desc

The description of the method or argument

key2

The name of the argument to be described. Only relevant for the latter two types.

type

The type of item to be described. This can be:

• 'instance' (instance method)
• 'class' (class method)
• 'instArg' (argument of an instance method)
• 'classArg' (argument of a class method)

The default is 'instance'

addExample(examplecode)

Add example code to the helpfile. These should be preformatted (e.g. with htmlize), and enclosed in 'PRE' tags

addExampleFromFile(filename)

Add example code from a file to the helpfile. The file should contain code (e.g. created with htmlize) that is enclosed in 'PRE' tags.

writeToFile

writes everything to file

examples

Array of examples to add in the helpfile.

classMethods

IdentityDictionary with the class's class methods. The second item in the array should be the description.

instanceMethods

IdentityDictionary with the class's instance methods. The second item in the array should be the description.

createClassMethods

creates the class methods. Is called when the classname is set.

createInstanceMethods

creates the instance methods. Is called when the classname is set.

writeHeader

writes the header for the helpfile. Called from writeToFile.

writeInstanceMethods

writes the instance methods to the file in HTML format. Is called from writeToFile.

writeClassMethods

writes the class methods to the file in HTML format. Is called from writeToFile.

writeArgDesc(argsDict)

writes the class or instance argument descriptions to the file in HTML format. Is called from either writeInstanceMethods or writeClassMethods.

writeExamples

writes the examples for the helpfile. Called from writeToFile.

writeFooter

writes the footer for the helpfile. Called from writeToFile.

Example 1

~hf = HelpFile2.new( "HelpFile2.html");
~hf.classname = "HelpFile2";
~hf.shortDescription_( "utility class to create a help file for a class" );
~hf.longDescription_( "This class can be used to create helpfiles for SuperCollider classes. You can create a helpfile fully from the SuperCollider language. The only thing you may want to do afterwards is rearrange the order of the method descriptions. This class creates a readable HTML, so it will be easy to do so.");

~hf.addDescription(\new, "Create an instance of HelpFile2, with the name (should be the classname) and path pathName. If no path is given, it will create one in the current working directory and give it the classname and the HTML extension.", \class );

~hf.addDescription(\createDoc, "Creates a document which contains a blank template to fill out with descriptions and execute to create the helpfile. varname should be the variable name you gave to the HelpFile2 instance (e.g.\"~hf\", like in the example below)");

~hf.addDescription(\createInstanceMethods, "creates the instance methods. Is called when the classname is set.");

~hf.addDescription(\createClassMethods, "creates the class methods. Is called when the classname is set.");

~hf.addDescription(\writeInstanceMethods, "writes the instance methods to the file in HTML format. Is called from writeToFile.");

~hf.addDescription(\writeClassMethods, "writes the class methods to the file in HTML format. Is called from writeToFile.");

~hf.addDescription(\writeArgDesc, "writes the class or instance argument descriptions to the file in HTML format. Is called from either writeInstanceMethods or writeClassMethods.");

~hf.addDescription(\classname, "the classname for the current helpfile.");

~hf.addDescription(\classname_, "sets the classname for the current helpfile. This autogenerates the instanceMethods and classMethods.");

~hf.addDescription(\writeToFile,"writes everything to file");

~hf.addDescription(\writeHeader,"writes the header for the helpfile. Called from writeToFile.");

~hf.addDescription(\writeFooter,"writes the footer for the helpfile. Called from writeToFile.");

~hf.addDescription(\writeExamples,"writes the examples for the helpfile. Called from writeToFile.");

~hf.addDescription(\instanceMethods, "IdentityDictionary with the class's instance methods. The second item in the array should be the description.");

~hf.addDescription(\classMethods, "IdentityDictionary with the class's class methods. The second item in the array should be the description.");

~hf.addDescription(\examples, "Array of examples to add in the helpfile.");

~hf.addDescription(\shortDescription_, "Set the short (header) description for the helpfile.");

~hf.addDescription(\longDescription_, "Set the long prose description for the helpfile.");

~hf.addDescription(\addExample, "Add example code to the helpfile. These should be preformatted (e.g. with htmlize), and enclosed in 'PRE' tags");

~hf.addDescription(\addExampleFromFile, "Add example code from a file to the helpfile. The file should contain code (e.g. created with htmlize) that is enclosed in 'PRE' tags.");

~hf.addDescription(\addDescription, "Add a description for an instance or class method, or one of their arguments");

~hf.addDescription(\addDescription, "The name of the method", \instArg, \key);
~hf.addDescription(\addDescription, "The description of the method or argument", \instArg, \desc);
~hf.addDescription(\addDescription, "The type of item to be described. This can be: <UL><LI>'instance' (instance method)</LI><LI>'class' (class method)</LI><LI>'instArg' (argument of an instance method)</LI><LI>'classArg' (argument of a class method)</LI></UL> The default is 'instance'", \instArg, \type);
~hf.addDescription(\addDescription, "The name of the argument to be described. Only relevant for the latter two types.", \instArg, \key2);


// now HTMLize this buffer or region within Emacs, trim the header and footer portion in the resulting buffer and save it to file.

~hf.addExampleFromFile( "HelpFile2.scd.html" );

~hf.writeToFile;

~hf.close;

// Now open the file again within Emacs, and rearrange the class and instance methods a bit.

This helpfile was created with the class HelpFile2