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

Re: [sc-dev] Adding Help files to SC3, sourceforge


On Wednesday, December 10, 2003, at 01:14  AM, Sean Costello wrote:


Hi:
It seems like there are a lot of missing help files in SC3, that do have corresponding help files in SC2 and SC3d5. Every now and then, I port over some of the missing help files, but then they are wiped out when I update to the latest SC3 binary. Instead of whining about this, I would like to check 
in the help files as I update them, so they can be distributed with the
build.

A few questions:
1) Do I have to register as a developer, get competent with SourceForge, and 
all of that? Or can I send them to someone to check in for me?
You can join or you can send them to me if you like. Or just tell me which ones. I'd been slowly moving them over, and I think most are there now, but I've been a little busy as I was on tour, etc. Any ones in particular?
2) Are there some general policies I should follow when porting? I tend to 
like the examples of the form {}.play, but I know that this is not the
current paradigm. If the old examples had {}.play, should that be used, or 
should I come up with something along the lines of
SynthDef("help-thingy", {arg thing=0, superthing=0;
    stuff;
    Out.ar(out, stuff);
}).play(target,args, addAction) ?
I don't think there's a definite policy on this. But there was a debate about the validity of Function-play, and the final decision seemed to be that it's not just there for backwards compatibility, so I think it's fine providing it doesn't obscure anything in the examples. I added a bunch of stuff about this to the Function helpfile.
3) Do the help files need to be as terse as they currently are? In a lot of cases, only a few of the parameters are defined. I tend to be of the school of explaining all parameters, if possible (I can dig into the source code if 
need be), including operational bounds.
Again this was a debate, but I come down on the side of complete documentation, excepting 'private' methods. I think everyone was in agreement that inherited methods should not be documented in subclasses that inherit them, as this can result in major documentation bloat, and there are by now several documented ways of tracking down inherited methods. By parameters do you mean methods, arguments? Just be sure when you add something that it's really accurate. Some of the methods and their purposes are a bit opaque. 

4) Is there an approval process in place for new help files?
Post em to the list? Send em to me? Or just give people a heads up that you've added them, and you'll find out soon enough if they're bad. Personally, I'd appreciate you letting me know what you're working on. SInce I've been working on this I'd rather not duplicate effort. 

S.