[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [sc-dev] Guidelines for helpfiles [comments?]

Since Sean asked:

Regarding guidelines for helpfiles, there are some on the swiki:


Beyond this in general follow the existing formats, i.e.

Text in Helvetica 12 pt, code in Monaco 10 pt (Some older ones are in 12 pt; I propose we standardize to 10). Syntax colorize the code.

I propose we ashould stay with 9 pt monaco for now. Someday there should be a scaleable SC font that looks good. 10 pt anti-aliased monaco doesn't look very clear, at least to me.

all the other guidelines I fully agree with (also the indented style)

At the top state the class (or helpfile) name in bold Helvetica 18 pt, and immediately below that the superclass in bold 12 pt.

Method names in bold. Class methods should begin with an *. In general sort the methods into logical sections, which should be labeled in Helvetica 14 pt bold underlined.

References to other helpfiles should be in bold or in bold within brackets [ ] for easy selection. Currently this is not consistent, but i've got a little time now, so I'm going to try and get then html help working today and tomorrow. In that case these can be replaced by links, and this issue will be irrelevant.

There are two styles of listing methods. The old style, and the new indented style:

Old style:


superclass: nil

Object is the root class of all other classes. All objects are indirect instances of class Object.

Class membership:


Answer the class of the object.



Answer a Boolean whether the receiver understands the message selector.
Selector must be a Symbol.

New indented:

Node Commands

	See also the Node Commands section in [Server-Command-Reference] .

			stop this node, remove from its parent group
			Once a Node has been freed, you cannot restart it.

pause or resume processing for this node. See examples in Synth.


I personally have no issue with having both of these. I feel the latter is more appropriate for things that require lengthy method explanations.

Any thoughts on any of this?

If nobody has any objections to these guidelines I'll add them to the swiki, and to CVS as well.


sc-dev mailing list