Talk:Policy: Scripting Command Page Syntax

Proposal

Values and commands are written with leading lowercase

Types are written with leading uppercase.

Syntax line:

The parameters should be specified as names only, with types specified below, like this:

Syntax: a min b

Parameter 1: a: Number

Parameter 2: b: Number

In the syntax line the parameter names are plain text, command is written bold.

What to do with array parameters?

--Suma 10:36, 6 September 2007 (CEST)

Type only alternative

Currently Mikero seems to be doing a lot of work changing docs into a different syntax, like:

• Object = nearestObject Position
• Object = nearestObject [ Position, "ClassType"]
• Object = nearestObject [ Object, "ClassType"]

What I do not like about this is arguments are not named, only their type is given, which seems confusing to me. However, it is clear such syntax is more concise and leads to shorter definitions. Still, I think it is not informative enough and I am against using it. Based on my proposal, this should look something like:

• object = nearestObject position
• object = nearestObject [ position, classType]
• object = nearestObject [ sourceObject, classType]

sourceObject: Object

object: Object

position: Position

classType: String

--Suma 11:02, 6 September 2007 (CEST)

Mixed alternative

Mixed alternative could be to have both name and type specified at the same place, like this:

• object:Object = nearestObject position:Position
• object:Object = nearestObject [ position:Position, classType:String]
• object:Object = nearestObject [ sourceObject:Object, classType:String]

or perhaps even using types only as links (very consise, but perhaps not that clear):

• object = nearestObject position
• object = nearestObject [ position, classType]
• object = nearestObject [ sourceObject, classType]

--Suma 11:43, 6 September 2007 (CEST)

In my view the major change i made was to indicate very very clearly which commands returned values by saying so as part of the formal syntax. The descriptors of what they return might be too nebulous in some cases. The return and it's type, if any, was sometimes buried underneath several lines of blurb about paramaters.

I think you are over-stating the case with 'object' to make a point that 'object' generally doesn't have enough meaning to the context of the command. I definately agree it is too nebulous for most commands when 'vehicle' 'unit' or some other highly descriptive syntax can be used.

But in the above example it's the "right" descriptor to use as it is intuitive ie, what other 'thing' would you be looking for with nearestOBJECT other than???

as far as Object : object eg, my view is that it is too noisy. The command syntax (as opposed to examples) should be (as far as possible) at-a-glance.

Object | sourceObject

definately don't like this hidden link. it infers that a sourceobject is some kind of 'type'. For me, Object | unit and Object | vehicle are very clearly subtypes. Eg units and vehicles (and persons) are generic enough while being specific enough. Specific enough == many commands that are intended to work with 'vehicles'. They dont need 'tank', or 'SomeCar' in the formal syntax.

sourceobject on the other hand is in context only to the command, and in that instance I like the current style of defining it AND as a paramater, post syntax, per specific command.

There are, two broad categories of paramaters used in command syntax, one group, a large body of the commands, work on 'persons'. It would be silly eg, to say 'soldierOne' or some such in the syntax for that group. I believe. person, unit and vehicle is 'right' for them (or something similar). I hope that, barring typos, where i did stat Unit for a command, I _also_ declared it as a subtype of Object in the parameter field. (i think doing so is a good idea (tm) )

the other group is highly specific, per command, FogIntensity is far far better to use, in the syntax and in context, than something like 'number', on an individual basis.

as far as math functions go, as formal syntax 'a command b' is somewhat meaningless, and 'number' is also pretty awful. I'd suggest radians degrees, angle etc where appropriate (with an accompanying radian = number in the parameter description)

also, i noted that the terms unit (mostly) and person got mixed around in some decriptions. Sometimes unit implied soldier and could only be a soldier, other times it implied vehicle-only. The overall effect of which was to confuse the reader what a 'unit' was. And, in some descriptions the word vehicle was used when it clearly was a person. Have tried to clean those typos out.