Typographical discipline in GDL - new guidelines

[david nicholson-cole]

Dear GDL Friends,

I have been asked for my opinion about a proposed change in Graphisoft's guidelines for GDL. For many years, the GS guidelines and the system promoted in the GDL Cookbooks and Object Making books have been Upper case for keywords (BLOCK, SQR(), TAN(), TUBE etc) and lower case for parameters and strings and comments.

The proposal from GS is that ALL script should be in lower case - keywords, commands, parameters etc. The justification appears to be that this is how things are in java, C etc. and its good to shake off the heritage from BASIC.

This is something I fundamentally disagree with.

But if you agree with me, then I need some supporting emails from the GDL developer community. Ed Brown of the GDL team at GS would like to know how the developer community think.

My arguments are:

The machine may not mind what case the script is in, but the human brain cannot read pages of script easily if there is no system of distinguishing keywords from parameter names and strings.

Since Graphisoft have not seen fit to provide smart colourtext (as in Dreamweaver etc and Visual GDL of 1995-6, and Codewarrior) whereby colour is used to distinguish keywords, comments, parameters, strings, the poor human working with the script needs some way of distinguishing words in the script. Good java and C++ editors like Codewarrior used coloured text.

The tendency for parameter names to get longer and longer means that it is more important than it ever was to use a system of Typography to distinguish keywords from parameters and strings. In java, C, pascal etc, there is also a very disciplined system of progressive indenting, to highlight blocks of code and help the brain pick out the blocks - I also promote this in my recent books.

In the old days of AC 4 and 4.5, we used single letter variables, and if these were upper case, there could be an argument for making the keywords in lower. But even then, the GDL book from GS recommended the system proposed in the Cookbook. And since AC5, parameter names could be longer.

The new languages on the block like HTML and XML can use Upper case for keywords (FONT, STYLE etc) and lower case for strings etc, and this is a perfectly good precedent for arguing that GDL should stay with a mixture of upper and lower case. (they also use coloured text in Dreamweaver and Golive editing. Dreamweaver 4 uses lower case, but as its coloured, I dont have a problem with that.).

The need for modularity and maintainability and upgradability is essential for GDL libraries, and vast masses of text all in one case and colour inhibits maintenance.

GS Manuals, Autoscripts and DXF / XML import translators etc all work to the Cookbook/old GS guidelines, so why should Human GDL writers be disadvantaged?

----------------------------
Please can you write to me directly or on here so I can assemble a case. Ed Brown at Graphisoft has very kindly offered to consider the opinions of GDL developers and compile them for consideration by the GDL development team - but I dont think he wants to be deluged! so put them here or send copies of them to me privately at davidnc@gdlcookbook.com .

Remember, these are only guidelines, this discussion is not about changing GDL - so it is not life changing. But i will certainly NOT plough back through 200 pages of GDL Cookbook 4 and change everything to lower case!! And it does mean that future objects in GS libraries will be even more impenetrable to editing or maintenance.

Frankly this seems to be a case of something that ain't broke and doesnt need fixing. There are many other improvements in GDL that we can all think of and that we would prefer the team to be thinking about - like smart coloured GDL script.

>>>david

[Ralph Wessel]

david wrote:
Since Graphisoft have not seen fit to provide smart colourtext (as in Dreamweaver etc and Visual GDL of 1995-6, and Codewarrior) whereby colour is used to distinguish keywords, comments, parameters, strings, the poor human working with the script needs some way of distinguishing words in the script. Good java and C++ editors like Codewarrior used coloured text.

It would be great if GS added colour-coding to GDL scripts, but their text editor needs help in many other ways too. I find it very frustrating to use. One alternative is to use an external text editor and copy/paste scripts across as needed. Many text editors can be 'trained' to recognise keywords from other languages like GDL too.

david wrote:
The proposal from GS is that ALL script should be in lower case - keywords, commands, parameters etc. The justification appears to be that this is how things are in java, C etc. and its good to shake off the heritage from BASIC.

I would personally prefer to type commands in lower case because it makes it much easier to switch between GDL and other languages. There is a strong trend to certain conventions across many languages and I think this is one reason why GS might contemplate this change.

Who knows what other changes the future might hold? Perhaps they are also contemplating a shift to a more object-orientated approach to GDL in future, which would fit well with a change in standards. It's also worth considering that if you want to be involved in software development of any kind, you must be prepared to periodically drop old conventions/languages/algorithms/designs. These things have to change in step with new opportunities and challenges. I sincerely hope that this proposal hasn't been tabled purely for aesthetic reasons though.

BTW, it wouldn't be difficult to write a tool to automatically reformat all the scripts in your existing GDL objects to whatever convention you like.

david wrote:
The new languages on the block like HTML and XML can use Upper case for keywords (FONT, STYLE etc) and lower case for strings etc, and this is a perfectly good precedent for arguing that GDL should stay with a mixture of upper and lower case.

XML is case sensitive, so "EDITOR" is not the same as "editor" or "Editor". The choice to use upper/lower case is left open, but you have to be absolutely consistent.

[Anonymous]

The more I thought about it, the more I realized that the editor I would like to see is essentially Microsoft's Visual Basic 6 editor. It has color coding, automatic function capitalization, and tool tips that pop up after keywords that remind you of the required arguments. It's a great interface that helps you code faster, and -- if you are still learning GDL -- helps teach you by it's hints.

Now, after they fix the editor, let's talk about the code optimizer...

[__archiben]

as somebody who's knowledge of GDL is about on par with my ability to perform brain surgery, i have kept out of this one . . . so far!

but when i have dabbled, i have been intensely frustrated by the editor and its inability to distinguish keywords, variables, etc at a glance and without the need to get creative with plain text.

david - i know that you are a strong advocate of plain text, and if this is the route that the GDL editor is taking for the foreseeable future, then i strongly agree with you - the need to distinguish keywords as CAPS should remain.

however. i would prefer to see the kind of syntax highlighting and line numbering available in most other code/scripting editors (including 3NF, which has now dropped it's mac support i notice. ). if the GDL editor were to take this route, the use of all lower case text would cause me no offence (as you can see from 99.9% of my posts here and anybody who has received an e-mail from me: the use of capitals is something that i consider optional )

now, thinking ahead:

Jay wrote:
The more I thought about it, the more I realized that the editor I would like to see is essentially Microsoft's Visual Basic 6 editor.

no! lets go the dreamweaver route: combined 'code' and 'design' views. a 3D 'design' window for editing your object with 3D tools (possibly the addition of 'mere' surface/polygon tools. NURBS and the like: remember we don't necessarily need object-based 3D tools in GDL as we are making the objects themselves to be used in the model).

changes are updated automatically in the GDL 'code' view. of course the 'code' view can also be edited with changes reflected in the 'design' view, (if the code is correct!).

naturally, this 'code' view would have line numbering and syntax highlighting which would also have an optional preference to display keywords in CAPS (if the text can be coloured . . . why not? the 'compiler' would handle the real case-sensitivity in the code wouldn't it?)

let's also allow for the multiple windows to be controlled and edited in a far cleaner and intuitive manner than is currently possible.

and: code snippets and a pre-emptive 'help' palette that changes to reflect the current keyword - showing immediately the correct syntax and status codes needs to complete the 'command' correctly . . .

now to qualify: i don't have a clue what i'm talking about when it comes to GDL, (or indeed programming generally), so stop me if there are fatal flaws in this grand plan . . .

oh. and graphisoft: start playing by your own rules, eh?

~/archiben

[Ed_Brown]

I have gathered a few quotes to the seminal post that David placed last week concerning the GDL standards and typography. One thing I do wish to note about his post is the following quote:

…But if you agree with me, then I need some supporting emails from the GDL developer community. ---DNC


In GDL talk and ArchiTalk there was significant supporting email. There were also some emails that were not completely supportive. There were also a few emails I received direct that did not appear on either forum.



SCATHING CRITICISM:

“GS won't do anything to make scripting easier, but here's something we can do voluntarily to make it harder. No way.” –James Murray

“Case, indents and comments are the only tools we have to make scripts readable. I see no reason to promote a standard which abandons one of these features.” -Matthew Lohden

“…We’re a community of designers grappling with programming, we're not C programmers!” -Cameron

“…All anyone has to do to understand the importance of this is to open an old Graphisoft library part and try to understand what's happening.” - David Collins

“Please GS, don't change the rules in the middle of the game. (notice that GS standards are not respected in their own libraries)” – Olivier Dentan



MAYBE THE CAPS ARGUMENT ISN’T SO BLACK AND WHITE

“Ask any 2 and you'll get a different answer.” – In response to what do your GDL programmers prefer -anon. **

“I think that putting keywords in lowercase is a non-issue, and think that GS
should put that in their standards if their employees will be more
productive (as some of us are) coding that way ... and it eliminates the
'dated' look of keypunch/teletype-days BASIC.” -Karl Ottenstein on GDLTalk

“Speaking as someone who works with vb, java, C++ and GDL, and other older languages such as ExpressX, can I say that I actively prefer lowercase keywords…. Sentences do not contain upper case unless someone is shouting.” –Nicholas Nisbet on GDLTalk



MAYBE THERE IS SOMETHING OF VALUE IN THE GUIDELINES…

“On the other hand the proposal to use something like "xRailPos" for a parameter that is described as "X coordinate of a point" with changing lower and upper case is a very good idea, which fits good to David’s wish for clarity in the scripts. And there are a lot of other very good proposals in the style guide, that also work for clear arrangements in the scripts.”



It is time to move on…

“In summary, the fact that GDL is derived from BASIC does not mean it should stick there. I don't believe that GDL people want to produce basic objects. To cite the example of modules like RoofMaker, Wall Extras etc., we would all like GDL to extend beyond creating barstools, keyboards and microwave ovens. Users want intelligent, interactive, self-updating objects that fit into the production process (that also means access to the calculate functions). If we get bogged down into debating upper vs. lower case, we may never get round to the big picture
issues.” -Michael Muriithi on GDLTalk



The people here at Graphisoft admit the original work in progress guideline was not too prudent and have corrected it. That is, the GDL Guideline now reads:
“Commands should be written consistently lowercase or uppercase according to your taste”

But that certainly does not summarize the main push of the thread for a more up-to-date GDL editor/ Programming environment. The ability to more clearly present the structure of a program with color was quite loudly presented.

Speaking for Graphisoft I cannot promise our programming environment will change in the near future. Graphisoft’s goal is to help architects build great buildings and our GDL language developers have their hands fairly full working on better language algorithms, supportive GDL kits for developers like the LibDevTool, additions to the next version that includes a basic library, enhanced documentation and the upcoming style-guide.

Personally, I will work hard to convince people within the Graphisoft development team of the significance of this editor issue especially in the light of this past thread. It is my hope that as Graphisoft makes GDL a more robust language it will also improve the editing environment.

Thanks to everybody that participated in this exchange. I had a hard time selecting material from all of the ideas and criticism presented.

Your criticism, suggestions and support are very welcome.

Ed Brown


**(The message was sent direct to me, not posted on ArchiTalk or GDLtalk –which is why I have left off the name of this quote.)

[tsturm]

Holy COW!

So many comments and additions to the topic of whether to use CAPS or not. There are so many great requests in this post. So many references to other applications and how they do it.

I am no PRO at my GDL programming. I do it because I see the need to have parts which are flexible. I find that there are many AC users out there who never see the light of day of GDL. They just jump into using AC as if it were any other program. I amaze my coworkers at what I get done with the software. No back patting here. Just an observation of how others are using the software. So for those who get into the GDL for the very first time out of frustration with a library part. Or they finally get tried of creating a ton of parts and every possible variation just to get a drawing done. These people are amazed and very confused by the lack of structure to the GDL scripting area.

So things like color or CAPS is really necessary for these people. They need to see structure and organization to the text. For those out there who code on a regular basis, these features just make their life that much more enjoyable.

I am really suprised that it has taken GS soooo long to add some structure to the GDL scripting. I would have thought that GS would have made it so that the software would intend or add the missing command at the end of the beginning such as the NEXT command is added when the FOR command is typed.

I am sure you all have so many things you want added to make your life easier. I just want a way to get those people who enter the GDL arena for the very first time to be AMAZED by the ease of creating the parametric library parts. I want them to so feel comfortable that they continue writiing THEIR own code so that I can get back to doing my own designs. Instead of making parts for them to use to get their own messed designs to work.

I would love to see the day that the code meshes with the modeling. A way to model and code at the same time, back and forth. I want the process to be less writing. I want more scuplting, with the option to add a command to make it adjustable in just the right spot. A way of clicking on a drawn shape and seeing the code which created it. (yeah, a lot like HTML or XML) Only with the modeling environment.

Perhaps if the default generator of the code would be smarter in its creation of the script, then we would all spend a lot less time typing in the code we wanted in the first place. (yeah, a lot like the evolution of the HTML editor has gone) Only with the modeling environment.

so bring on your changes of colors or lost caps or line numbering, but just do not stop at this small little thing of text formatting. MOVE on to the next phase of modeling the GDL object. Spend your time getting rid of the typing of text to get a shape, completely. Once and for all. Make the jump to a smarter model converter which can create variables for materials, pens, fills and angles based on the object already modeled or drawn.

this is the reason why most of us are editing GDL. it is to make the stuff we have made into a parametric part. so that we do not need to make a mess our out drawings with lines and fills. we want parts which are flexible and adaptable.

so good luck and remember, make it backward compatible or brand spanking NEW

thanks

[Aussie John]

Applescript is a good example of script that complies using colour and indents automatically. I personally dont like capitals and find them awkward to type with (particularly when you forget to turn off caps lock and then realise after typeing a sentence it is in all caps)

Reading this thread I think the concensus is for automatic colour insertion for commands keywords etc.

I am sure the dedicated uses will hate this idea but as someone who can never remember the command syntax how about a optional feature that automatically fills in the remainer of the the command. ie type "circle2" and the generic paramaters fill to get "circle2 x,y,r" (so I dont keep having to go to the manual). This is particular useful with inconsistences in the commands eg hideparameter and parameters (one has s and one doesnt and I can never remember which!!

This would work by the editor accessing a library. This is already similar to feature of your internet browser or Textedit (on the Mac).
A side benefit would be keeping up to date with syntax is only a matter of keeping an current library in prefs.

[Anonymous]

David, you have my full support too!
We are architects who write scripts from time to time, not programmer who do it all day long. That is why script-writing whould be made more easyly accessible for us.
And greet the idea for colours - hope we'll see it realised soon!

[Anonymous]

Aussie wrote:
Reading this thread I think the concensus is for automatic colour insertion for commands keywords etc.

I am sure the dedicated uses will hate this idea...

I have been writing GDL code since 1989 and I very much like the idea of color coding and auto indenting.

I have always appreciated these features when I have used them in other programming environments. I once even set up a programming text editor (AlphaEdit I think) to do this for me and then copy/paste into the GDL editor.

Besides making the code more readable, the color coding also serves as a spell checker.

[Anonymous]

Wow I've been out of the loop for a while. I keep my head down working for a while and you guys get all philosophical on me.

On the occasions I've had to crack into a GS object to figure out how to do something, I ended up throwing up my hands and giving up. It's too hard to weed through the structure, trace back values and find exactly what you need without completely picking it apart and wasting a lot of time.

I've only been at this for a couple years but one thing that has stuck with me is DNC's caps and indentation structure. The Trus Joist objects have gotten so complex that without this structure, or had I followed GS's example, the script would resemble a bowl of spaghetti noodles. That structure has saved my bacon many a time and countless hours.

This structure is all I know since GDL and HTML are the only things I write in. Unless GS can come up with a better solution (i.e. colored key words like AutoLISP Editor in a cad program that shall not be named) this structure should be adopted at least for the time being.

[Karl Ottenstein]

I don't think @Ed_Brown is involved with this any longer - 17 years later (!) - if he is even still at Graphisoft.  But, it does seem long past time to get an automatic color-coding / indenting / smarter editor for GDL - potentially a perfect project for a new Graphisoft programmer to cut his/her/their teeth on. 🙂