Talk:Syntax

A draft for a syntax article, please add/change anything if there's something missing. I think we can make the Syntax: on the function pages clickable and linking to this article. With the wiki bot of course, not by hand. Good idea?
--Qazaaq 17:24, 10 September 2008 (EDT)

An excellent idea. All for it.

A thought just occurred to me - might it be appropriate to have a Template for syntax? It would be a bit complicated to write, and it might also be complicated to use, but it would also ensure standardization. Advantageous?

Dragoon Wraith TALK 19:55, 10 September 2008 (EDT)

A template for the syntax sounds like a good idea. It shouldn't be hard to write, replacing the syntax on the existing function pages is harder. We don't want the bot to mess up existing syntax that's not following the rules. I should really look into the bot more, it should be possible to create pages for new OBSE functions automatically. But let's finish this first.

--Qazaaq 09:34, 11 September 2008 (EDT)

Would something like Wrye's setup for the Raw Function List help? That is, a "database" of all of the functions and their parameters, then use a bot to write up the functions from that database? I think this would be possible with vanilla functions - check out this page. Note Daveh is the author of the page, so he may still be able to help us. (and at least one point of interest - DuplicateAllItems has 2 parameters)

--Haama 19:13, 11 September 2008 (EDT)

One other note (when we get a chance to pick this up again) - we can't assume that refs as arguments are always base objects, even for OBSE functions, or, more importantly, that they're either base objects or refs instead of base and refs (i.e., IsFormValid).

--Haama 12:10, 5 October 2008 (EDT)

Been a while, so I'll go to the left.

I was thinking about this last night, and am wondering about a few different possibilities. I'm not sure if these will work, so I'll be looking them up.

1. For the returned value when there is nothing returned
   • Proposals:
     1. Show blank parenthesis ()
        • It'd be a few more characters than necessary, but it would prevent any confusion over whether the parameter was forgotten or there really isn't one.
     2. Show nothing
        • Most of that confusion stems from the multiple formats throughout the wiki - if we are able to switch to a single format the confusion should be gone anyway.
2. For the dot syntax and base/ref record:
   • There can be two variables here in the form ref.Function ref
   • The dot syntax isn't always allowed (i.e., Math functions), is 90% of the time a reference as opposed to base objects, but can be a base object.
   • The second ref is usually in OBSE functions and is a base object. However, there are a few vanilla functions - some expect base objects (i.e., PlaceAtMe) and some expect a reference (i.e., GetDistance)
   • Proposals:
     1. We treat these two parameters uniquely. The template should ask - Is Dot Syntax allowed? Does it take a second reference? Are both required or is it either...or?
     2. The specific type (base or ref) can be specified for both
     3. We need something to show the "Either...Or" status - maybe different colors, maybe make them bold, maybe just denote it in the function text. I'm not sure on this one.
3. For parameter types
   • This really depends on how much information we want to display and how much we can leave to the user to know. I think there are 3 different levels of information that can be provided
     1. Parameter name (i.e., ActorValue) - this is the most basic, and we would assume the player can figure out whether it's bool, int, ref base, etc. from background knowledge (meaning there needs to be a good article for that background knowledge). Even in the slightly ambiguous case of ActorValue the modder should know if it's chars or int based on the name of the function (if it has a C for Code). For codes (like ActorValue) we continue to display the chart as we do now.
        • This might be more than enough, however it's hard for us to guess what will be obvious to those just starting.
     2. Parameter name + Type - much like in the OBSE docs. The number of parameter types should be limited to the basic ref, int, float. The names should be short (some functions can have a lot of parameters).
     3. Full subset of parameter types - that is, if the reference has to be a magic item then we specify it (maybe MgcRef). This would leave all ambiguity behind and be crystal clear for anyone just starting. There are a lot of sub-types, but we already have a good deal of them in templates. This would also make it easier to update any information across all functions, though it may be obscure for editors.
        • There are a few variations we can do with this last one.
          1. We could write out the full sub-type (i.e., "RecRefActor.SetArrowProjectilePoison poison:RecBaseAlchItem")
          2. We could write only the parameter name in the function, but make each link to the appropriate sub-type page. ("ref.SetArrowProjectilePoison poison")
          3. We could display a tooltip (I think that's the word - box appears when user hovers their mouse over the word). This tooltip could display all of the information (i.e., all ~40 Actor Value codes) or the basic type (int, ref) with the limits (i.e., 0-255) and the reader can click the tooltip to be taken to a page with more information.
          4. We hide the information on the page until the reader clicks on the parameter. We'll need to make it clear which parameters belong to which sub-type, so we can use abbreviations (i.e., RBAI). We could, also or instead, display the parameter names next to the sub-type (i.e., "Base Record Alchemy Item (poison)")
   • Proposal - I like the last one best. It would probably be the easiest to do, the reader doesn't have to go to multiple pages, and the information is hidden for those who just need to glance at the page. I'll try to make an example with the function HudTInfo, and then make a template from there.
4. Alias
   • Proposal: We leave in a box for Aliases and the template should be able to handle the second line with the Alias
     • We could also give a list of Aliases below the Syntax, instead of the second syntax line.
   • Would a bot (or even the template) be able to create the Alias page and redirect?
5. Examples, Notes, etc.
   • Can templates leave space for other areas? Should we try to keep everything from the template up top and everything extra down below?
6. Centralized list of function information
   • The list of functions provided by Wrye Bash is nice. If we could find a way to extend it so it also drags parameter types from OBSE, then it would make a lot of this much easier.

--Haama 12:13, 13 December 2008 (EDT)

• One point about param types. IMO, for OBSE and plugins, param type info should duplicate what the author uses in thier own documentation. For example while 'short', 'long', and 'int' are all the same as far as script variables are concerned, internally a function may use a true short, so trying to pass it a larger number may break it or at least produce unpredicatable results. I recall Elys saying that this was the case with some Pluggy functions and I believe it applies to some OBSE functions as well.
• Regarding the various ____ID types (from Pluggy/TSFC/NVC/others). I think it would be best just to go ahead specify the type as ___ID with a note one the plugin's main page, like I did in the NVC docs. If you go ahead and list the type as int/long, you're just going to have to eloborate in the name to clarify that it is an id of whatever type....
• A seperate term needs to be used for the OBSE functions which take format string + format params + other params. There are many, many functions which take a string literal by itself with no formatting. The term string itself should be (and currently is) used to refer to them.
  

--Speedo 15:41, 13 December 2008 (EST)