Re: [swarm-hackers] Re: Host platform dependence (was Naming conventions)

[Bill Northcott]

For Nima  - How the documentation is done

While we are on the subject of docs:

Look in the SVN at the docs directory.  

The swarmdocs subdirectory contains the code that generates multiple versions 
(html, tex, pdf etc.) of the Swarm Reference from the code embedded in the 
comments of the header files.  It is an MD special of elisp, XML, xslt and 
friends.  These documentatation headers need to be kept up to date (see below). 
 This should be documented on the Wiki. (Yeah, I know: Do it yourself.)

The swarmguide contains the code to generate multiple versions of the User 
guide from the SGML original in the same directory.  Changes to the UG should 
be made in the SGML.

Have a look at src/activity/activity.h  You will see a load of comment lines 
beginning with //S: , //D:, //M: etc.   Now look at the Reference Manual 
section on activity and you will see how those comment lines correspond with 
the eventual documentation.

Hope his helps
Bill

On 19/11/2009, at 5:29 PM, Scott Christley wrote:

> The user's guide is a little out of date but many of the concepts are still 
> valid, plus the documentation
> 
> http://www.swarm.org/swarmdocs-2.1.1/userbook/userbook.html
> 
> http://www.swarm.org/swarmdocs-2.2/set/set.html
> 
> 
> On Nov 18, 2009, at 10:20 PM, Nima Talebi wrote:
> 
>> I think - we need a "Nomenclature Definitions" page on the swarm wiki, with 
>> a nice definition of each... so everyone is on the same page.  We can maybe 
>> forbid some terms all together.  It can be part of the "Induction to Swarm" 
>> section of the wiki which I'll be creating first.
>> 
>> Nima
>> 
>> 
>> 
>> On Thu, Nov 19, 2009 at 5:13 PM, Scott Christley <address@hidden> wrote:
>> Yeah, it's true, the 'model' word is bad, right behind it is 'system' and 
>> 'paradigm' and many others.
>> 
>> Anyways, I'm using the word model in the same context you are.  The 
>> integration piece I'm talking about is the ObserverSwarm.  This is part of 
>> the Swarm design and defines how the simulation of the model is observed.  
>> The observation could be a GUI but its also possible to be non-GUI like 
>> saving data into a file.
>> 
>> No it's not typically part of the modeller's model, but it is part of the 
>> Swarm Library.  The distinction is well defined.  The interface is not.  
>> According to the Swarm design, the ObserverSwarm object is also a Swarm 
>> object.
>> 
>> But let me put my "Glen Ropella" hat on for moment, some modeller actually 
>> may consider the act of observation to be part of the model.  No its not 
>> common, but its valid.
>> 
>> Scott
>> 
>> 
>> On Nov 18, 2009, at 9:25 PM, Bill Northcott wrote:
>> 
>> On 19/11/2009, at 2:03 PM, Scott Christley wrote:
>> Okay, so I think I understand your point, and I agree with it to a certain 
>> point.  Yes, I did a lot of work to separate the underlying scheduling 
>> engine, what you are thinking of as the "model source" from the GUI.  This 
>> has allowed Swarm to be exactly what you are suggesting with R, that is 
>> there is a core Swarm model, and then there is an "integration piece" with 
>> that Swarm model and the GUI.
>> 
>> Don't you hate this word 'model'.  It means all things to all people, and 
>> creates endless confusion.  In my discussion nothing in the Swarm library is 
>> part of the model.  The model is the code written by the modeller to model 
>> some reality she wants to investigate.  That model code should be written 
>> using only the Objective-C (or Java?) APIs documented in the Swarm reference 
>> manuals.  The implementation of those APIs is the Swarm library, the code 
>> for which is platform/GUI dependent, and may be any mishmash of tcl/tk, 
>> Openstep/Cocoa/Python/.Net or whatever
>> 
>> I am confused by your reference to 'integration piece.'  Is the integration 
>> part of the modeller's model or the Swarm Library? I really think the 
>> interface between the two needs to be clearly defined.
>> 
>> But one of your underlying assumptions is false, which is that the 
>> "integration piece" required to use the tcl/tk/blt GUI is somehow very 
>> similar to the "integration piece" required to use the OpenStep GUI.  That 
>> just isn't true, in fact they are very different and it necessitates a 
>> different interaction between a core Swarm model and the GUI.
>> 
>> Hence this does not makes sense to me.  I am certainly not assuming that the 
>> code within the Swarm library to implement the GUI Swarm APIs is in any way 
>> similar for tcl/tk/blt and Cocoa/Narrative.
>> 
>> Does that mean it prevents the core Swarm model (identical model source 
>> code) from having both an OpenStep GUI and a tcl/tk/blt GUI?  Absolutely 
>> not, it just means you have to write two "integration pieces", one for each 
>> GUI.
>> 
>> This also confuses me.  The modeller's model has neither a tcl/tk or 
>> OpenStep GUI.  If it a is a GUI model then it will create a Control Widget 
>> and if it defines probes, graphs or spaces these will create displays.  How 
>> that is done beneath the hood is not the concern of the modeller.
>> 
>> Now you do make the point about putting Cocoa code in the library which 
>> supports standard Heatbugs model and etc.  I'm okay with that for some core 
>> things like EZGraph, probes and etc.  But note that this still requires 
>> writing two "integration pieces", they just happen to be provided by Swarm.  
>> And this goes back to the point of how the two GUI have very different 
>> interaction models, the current design of Swarm is based upon the tcl/tk/blt 
>> interaction model, and that just may not be "doable" identically with 
>> OpenStep.  It requires more study, but when I looked at this more carefully 
>> in the past, I'm fairly confident that it would require significant changes, 
>> i.e. its not possible to "squeeze" OpenStep into the tcl/tk/blt interaction 
>> model.  This is why OpenStep Swarm is using multiple threads and a specific 
>> interaction between the GUI and the model, etc.  That begs the question then 
>> of what is the best design that can support multiple GUIs, not an easy 
>> question.
>> 
>> '
>> 'Interaction models' : it is that word again.  Can we call this 'UI 
>> paradigm' or whatever to avoid confusion with the modeller's model?  The 
>> interaction between user and GUI at the level of control detail is not part 
>> of the model in my parlance.
>> 
>> As for the point of core Swarm models *not* using Cocoa stuff.  Well in my 
>> opinion that is purely up to the user.  If there is some cool, I need to use 
>> API in Cocoa, and you are willing to give up using that model on Windows 
>> under tcl/tk/blt or whatever, then go for it.  The purpose of Swarm isn't to 
>> limit what people can do.  If users want to write a highly portable core 
>> Swarm model, that can be easily done.
>> 
>> Of course any user can do what they like.  It is GPL code.  However, it 
>> greatly restricts communication if models produced by one modeller cannot be 
>> run by another.  We need to be able to write unambiguous documentation for 
>> modellers.  What programmers think is cool, easily becomes a modellers 
>> confusing complication.
>> 
>> Cheers
>> Bill_______________________________________________
>> 
>> swarm-hackers mailing list
>> address@hidden
>> http://lists.nongnu.org/mailman/listinfo/swarm-hackers
>> 
>> 
>> 
>> _______________________________________________
>> swarm-hackers mailing list
>> address@hidden
>> http://lists.nongnu.org/mailman/listinfo/swarm-hackers
>> 
>> 
>> 
>> -- 
>> Nima Talebi
>> web: http://ai.autonomy.net.au/People/Nima
>> gpg: B51D 1F18 D8E2 B702 B027 23A4 E06B DAC1 BE70 ADC0
>> _______________________________________________
>> swarm-hackers mailing list
>> address@hidden
>> http://lists.nongnu.org/mailman/listinfo/swarm-hackers
> 
> _______________________________________________
> swarm-hackers mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/swarm-hackers

smime.p7s
Description: S/MIME cryptographic signature