Newly rewritten developer docs for DSSS

[Bill Baxter]

Gregor Richards wrote:
> Bill Baxter wrote:
>> Gregor Richards wrote:
>>> Bill Baxter wrote:
>>
>>>
>>> *whew*!
>>>
>>> OK, I think that I covered these fairly effectively. When I first 
>>> wrote this doc, I had immediate peer review, but these additions did 
>>> not, so rewording suggestions are welcome.
>>>
>>
>> ...[good additions cut]...
>>
>>>  > And one comment:
>>>  > - "The 'set' command sets a setting" -- this not a very helpful
>>>  > description.
>>>  > It's not clear why you need 'set'.  It says it's for doing things
>>>  > 'on-the-fly'.  But what does that mean?  Is
>>>  >    prebuild = echo "Hi"
>>>  > not on-the-fly?
>>>
>>> I changed the wording:
>>>
>>> "The 'set' command sets a dsss.conf file setting while DSSS is 
>>> actually running."
>>>
>>> Better?
>>
>> Well, it still basically says "'set' sets a setting", which is 
>> defining a word by using the word.  It doesn't clarify what you mean 
>> by a 'setting'.  That should be explained.  Also, it might help if you 
>> explained in the 'set' section more clearly what problem 'set' is 
>> designed to solve.
> 
> I honestly haven't a clue how to make this more clear. I'm not saying 
> that it's at all clear, just that I don't know how to improve it. What 
> exactly a setting is is described in an above section, so repeating it 
> there wouldn't be helpful. If you can suggest a wording, that would help.

I see what you mean.  Yes the description in the =SETTINGS= section is 
good.  Maybe the best thing would be to stick in a (See Section 
=SETTINGS=) after saying that set sets a setting.


>> And as for the 'on-the-fly' part, which you changed to "while DSSS is 
>> actually running" -- are there other commands that do something when 
>> DSSS is not running!?
> 
> No, but there's no other way to set a setting while DSSS is running.

I don't get what the difference is between saying
   a = Hello
and
   set a Hello

They both seem to set a value while DSSS is running to me.  The main 
difference seems to be that 'set' can apply to a different section than 
the one it appears in.


One more question:  Is there some way to set up dsss.conf to build 
recursively?  For instance in the directory top/ there's a dsss.conf 
file that invokes top/sub/dsss.conf.  Will a sticking in a [sub] section 
do that?

--bb