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

[Julian Rohrhuber <rohrhuber@xxxxxxxxxxxxxx>]

Since Sean asked:

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

http://swiki.hfbk-hamburg.de:8888/MusicTechnology/517

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:

Object

superclass: nil

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

Class membership:

class

Answer the class of the object.

5.class.name.postln;

respondsTo(selector)

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] .



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

		run(boolean)
			"/n_run"
			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.

S.


_______________________________________________
sc-dev mailing list
sc-dev@xxxxxxxxxxxxxxx
http://www.create.ucsb.edu/mailman/listinfo/sc-dev

--








.