Template talk:Function

Templates considered harmful

I realise I'm coming in very late on the discussion: after the decision's already been made, in fact.

How much advantage do templates give in management terms? Any more than a regex search-replace would give? Looks to me like templates are there because they might, at some point in the future, provide a hypothetical advantage to administrators.

Their main real effect at the moment appears to be to intimidate and confuse users.

Take me for instance: I've been programming for quarter of a century; professionally for 15; I know more programming languages than will fit on my résumé; and I am already juggling ten languages in my work, and another half dozen or so in my free time.

So I look at a templated page, see it looks like line noise or some bastard son of lisp, and think "...nah. Maybe some other day," and close the edit box. I don't need or want to learn another language, just to edit a webpage!

So, to my point: I'm a professional (by at least some measures), and yet I am daunted by the idea of having to learn yet another language just to edit a wiki. How much worse must it be for regular users?

How are templates bad? Let us count the ways...

• They are intimidating and offputting.
• They prevent use of the skills of readers. Most people clicking the edit button will have existing, wiki-editing skills, but faced with a template, these skills become essentially useless: they can't edit the page without fear of screwing it up.
• Templates are for machines, not for pages maintained by people. We've seen that people editing templated pages assume that it's wrong, and correct it to proper wiki style; I feel that is both natural, and arguably correct to do so once a page becomes hand-maintained.
• Templates are obfuscated, which is really bad style. Even code you write for yourself should be readable by all, and that is infinitely more important for code that you want other people to read and maintain, without training or pay. Could your grandma understand {{{{{ThisAtrocity}}}}}?
• Apparently templates can only affect the beginning of the page, so instead of making the page layout logical, you have to shoehorn the data to fit the template, squooshing what should be footer date into the header (I feel moderately confident that there must be solutions to this one).
• They break page histories, since historical pages which used a different version of the template or other transcluded pages are "lost" and the original look of the page cannot be regenerated from the page history.
• They cause invisible dependencies in that if a user changes a template to fit better with one page, they may inadvertently break several hundred other pages.
• And they have been known to kill puppies and kittens.
• Even proposed templating discourages editing. I'm certainly not going to bother editing any more function pages before I've got to grips with the template, because it's just a royal waste of time if they're only going to need rewriting. And I can't imagine many people feeling differently.
• Sometimes I go to other pages to find out the markup for something. If, instead of the markup I'm lookingfor, I find some line noise on the first three pages I try, that's just a downer, and I might decide to do the thing I was trying to do in a less goodlooking way rather than remember how to do that thing in wiki markup. It's happened once here for me already.

Well, just a thought, and opinion. If templates are here to stay, then I'll accept it, learn the language, and use them. But I've got a million other things to do, it's low on my priority list, so I may never get round to it. And the function pages are off my list of possible ways to procrastinate until then. DewiMorgan 07:21, 21 April 2009 (UTC)

I think you have to understand something: Qazaaq, Haama, and I have been the only significant editors of the CS Wiki for years now. The CS Wiki does not make considerable use of Templates, because we didn't know how to use them at first either, but now, oh lord do we wish that they did. A lot of your points assume that pages will be maintained by actual human beings, which ideally is absolutely true and that's what we want. And Templates may prevent that. But from where we are coming from - doing things the way we want to make our lives easier later, seems perfectly appropriate. Because we anticipate a time when once again, no one else is interested in improving the Wiki. Everyone uses it, but very few contribute. Fallout's still new, so there's still activity here. Six months from now? A year? Two? I don't know. Maybe Fallout will do better than Oblivion in that regard. But at least for us, there's not a lot of hope in that direction.

DragoonWraith · talk · 10:38, 21 April 2009 (UTC)

Really good point. So good, it stomps prettymuch any potential argument against. Will I still edit in 12 months? No, I'm a flash-in-the-pan worker, not a long-haul worker, so I can't argue with that point at all. And even if you had the world's most awesome bots and regex wizards and root access to the server and DB, I can't see any other low-maintenance way of doing what templates do. They're imperfect, but they're better than the alternative. In that case, I guess I'll learn the lingo and try to help as much as I can before my inevitable running out of steam. DewiMorgan 17:11, 21 April 2009 (UTC)

Testing

I added the template to GetAnimAction. As far as I'm concerned we're ready to put it to use on all function pages.
--Qazaaq 11:20, 16 January 2009 (UTC)

General

Looks pretty nice Qazaaq. I've been working on some ideas and placed them on the other wiki's Syntax page. I've gotta' run so I'll look at this some more later.
--Haama 17:16, 12 December 2008 (UTC)

OK, got to look at it a bit more.

• For the link to the CS wiki page, should we assume that it has the same name (if there is one)? That would be one less field to worry about.
• We should add a statement about the origin before the syntax, as on the CS wiki.

--Haama 19:56, 12 December 2008 (UTC)

I've divided your answer into sections below with my response. This should be easier to follow.

--Qazaaq 23:16, 12 December 2008 (UTC)

I've created the Sandbox so we can test this out.

--Haama 06:09, 13 December 2008 (UTC)

Discussion about individual fields

CS Wiki link

For the link to the CS wiki page, should we assume that it has the same name (if there is one)? That would be one less field to worry about.
--Haama 19:56, 12 December 2008 (UTC)

There has to be at least one field for CS Wiki link to determine if there has to be one or not. Whether this is a boolean of some sort or the name of the article doesn't matter. Using the article name will allow for more flexibility. When the field is omitted the entire notice is left out.

--Qazaaq 23:16, 12 December 2008 (UTC)

Origin

We should add a statement about the origin before the syntax, as on the CS wiki.
--Haama 19:56, 12 December 2008 (UTC)

There's already a statement for the origin in there. It's just not showing in the example. It will display an error message if it's omitted, the current GECK should be specified with GECK1, FOSE function will probably have room for a version number and display a notice.

--Qazaaq 23:16, 12 December 2008 (UTC)

The Geck1 option was blank, so I filled it out.

--Haama 06:44, 13 December 2008 (UTC)

ReturnVal

Currently, if the return value is omitted this will show an error. If it's left empty it will show the empty braces () Haama suggested at the CS Wiki, if it's filled in it will obviously be filled in. I've chosen to fill in void in the example because I think that's clearer. Any thoughts?
--Qazaaq 23:26, 12 December 2008 (UTC)

I changed the template today so that if returnType is set to "void" nothing will be shown for return information as opposed to (void) appearing. If it is omitted an error will still be shown though. I don't think its necessary to explicitly show (void) or () or anything at all when the function has no return value. The fact that nothing is shown for return value (and the summary won't say anything about a return value either) should be enough indication that it doesn't return a value.

--SnakeChomp 00:24, 31 January 2009 (UTC)

I can't say I'm crazy about the return type being surrounded by parenthesis, but if that's what you're all used to I can deal with it. I do however think void types should be explicitly displayed. Almost every other programming language explicitly labels void functions as such.

-TastyWheat (talk - contribs) 15:47, 9 February 2009 (UTC)

I think if the returnType is omitted, it should default to (void); i.e. the opposite of what it does now. *shrug*

DragoonWraith · talk · 18:55, 9 February 2009 (UTC)

CategoryList

We need something clever for to handle the categories. I'm open to suggestions.
--Qazaaq 23:26, 12 December 2008 (UTC)

This refreshed my memory a bit (still looking through it, though) and may be useful for first timers.

--Haama 23:36, 12 December 2008 (UTC)

Why do we need something clever for categories? I don't see any benefit to putting the [[Category:Foo]] stuff into the template as an arugment when all the template does it repeat what you gave it verbatim. Categories can easily be specified outside of the template at the bottom of the page, which is conventional here, at least in terms of the pages beth created for us.

--SnakeChomp 17:06, 16 January 2009 (UTC)

Categories can be a pain to add, especially when we're talking about FOSE - for Oblivion, we needed one for Functions, another for OBSE Functions, another for the function type (i.e., Actor) and yet another for OBSE function type (i.e., OBSE Actor). The solution doesn't even need to be categories, though. Qzilla and Qazaaq created a Navbox for Projectile functions (again, Oblivion) that worked pretty well. If we can convince Bethesda to add some Javascript we can create Show/Hide/Collapsable boxes that contain a good number of links and let the reader know just what other functions are around.

--Haama 21:27, 19 January 2009 (UTC)

Dot Syntax and OBSE (expected FOSE) functions

Dot syntax is a weird one. For (99% of?) vanilla functions it is required, but the Self reference is assumed for all object (even those in inventory) and magic effect scripts. To make it even stranger, quite a few OBSE functions treat it as "Either...or" and you would have to place a reference record before the function (dot syntax) or place a base record after the function.

Display suggestions - Required/vanilla dot syntax should look the same as a required field. It's closer to a required field (necessary for Quest scripts) than an optional field, and the dot itself should disambiguate it from other required fields. Either...or syntax should also look required, but both the ref and base parameters should have an asterisk next to them.

Template suggestions - The dot syntax should be explicitly be named as such (DotArg as opposed to Arg0). If I've got this right, there are basically three types of dot syntax - None, Normal, Either...or. These three options should be the template parameter input.
--Haama 06:31, 13 December 2008 (UTC)

Function Parameter Types

I still prefer show/hide boxes. These would allow new readers to easily find the information (right on the page) and those who want a reminder to glance at it. More importantly, some of the parameter information is rather long and this would allow readers to easily (and by default) see the rest of the page. Do you think we should ask about them again?

As for the template, I think it would be straight-forward. Each function parameter would have an optional template parameter "Sub-Type". If Sub-Type is filled, then show the template {{Sub-Type}}.

Further expanding on this is not so straight forward (especially when I should be asleep :P). I'm thinking the layout should be

==Parameter Info== Show/Hide
#Parameter 1 Name: Parameter information (i.e., ''RunOnActivate'' runs the script)
Parameter 1 Sub-Type Information Template - Show/Hide

--Haama 06:30, 13 December 2008 (UTC)

This worth considering. Most of the functions don't have a lot of parameters, but hiding parts of the syntax information would be very useful for the larger ones.

--Qazaaq 11:40, 13 December 2008 (UTC)

Displaying the whole page, instead of the summary only

I was interested whether we could set up the rest of the page - the Example, Notes, etc. sections. This would help standardization, etc. So, I simply added

...
{{{summary}}}

==Notes==<!--
...

This does display the Notes section correctly on the page (see Sandbox), however when you edit the section you get the rest of the template

==Notes==<!--

categorization code (needs something clever):
-->
{{{CategoryList|}}}</includeonly>

--Haama 06:48, 13 December 2008 (UTC)

The example section shouldn't be a problem. The rest - maybe it's best to leave that of the template. It's simple enough (only two headers), and adding it to the template complicates things unnecessarily. Leaving it out would also allow for additional section if a function requires them.

--Qazaaq 11:36, 13 December 2008 (UTC)

See Also

Is there a way to shove it to the bottom of the page? (I have tried to find one, but never had any luck). As of now, there's no way to put anything between the example and See Also.
--Haama 20:38, 7 January 2009 (UTC)

Hmm, good point. No, I don't believe there is any way to force it to the bottom. Maybe then See Also should not be part of the template then. As it is the Template seems to do more than I would have it do, personally.

DragoonWraith · talk · 21:15, 7 January 2009 (UTC)

I've removed the See Also from the template.

--Qazaaq 10:55, 16 January 2009 (UTC)

Arguments

I did some playing around today with a Function Argument template to specify arguments instead of a bundle of template parameters and added an arguments parameter to the function template. It spits out its value verbatim, so you can use regular wiki syntax to markup function arguments if necessary. The main reason I experimented with this is that it is easier to maintain the sub template than it is to maintain the 40 arg0-arg9, optarg0-optarg9, arg0type-arg9type and optarg0type-optarg9type parameters. The other important thing about the function template is it will let you specify a set of valid values that you can pass to the argument, which is useful when function arguments take a specific set of values (as PipBoyRadio does, which also has a real world example of using the function argument template).

What do you folks think? I'm not married to the style I ended up with, but that's easy to tweak.
--SnakeChomp 00:22, 31 January 2009 (UTC)

The function arguments are excellent, I especially like the enum-type thing. Something I'm not certain about is having the alias in the Syntax. It's nice to have everything on one Syntax line, but I think it may be confusing. I don't have a better solution, so if no one else has any input on this I think we're done here.

--Qazaaq 17:32, 5 February 2009 (UTC)

Changed the way the alias is handled to give it a separate entry. The way the template gets used remains the same.

I vote "shortname" gets changed to "alias" - it usually is just a shorter name, but at least I seem to recall cases where it was used as a true alias. To be sure, Bethesda's GetSelf/This are true aliases.

DragoonWraith · talk · 20:24, 5 February 2009 (UTC)

referenceType

Is there a consensus on what should be used for the "referenceType"? Object/ObjectID/ObjectRefID, Actor/ActorRef/ActorRefID? What should I put if it can be either?
--Ez0n3 15:56, 14 January 2011 (UTC)

Be as precise as possible, unfortunately we have no standard. Feel free to set one.

--Qazaaq 11:20, 16 January 2011 (UTC)

More/Longer examples

I noticed Maran placed a rather long example on the IsInInterior page, which Cipscis later removed. I don't know if the example was wrong or not, but it got me thinking. Just now another individual commented on the lack of semantic examples on the function pages on the CS Wiki Community Portal.

As of now we've mostly/only provided syntactic examples. I think adding semantic examples are a good idea.

Assuming no one is against that; where are we going to put them on the function pages? A semantic example is easily twice the size of a syntactic example, and usually one isn't enough. So maybe a subpage is in order. Maybe we could add a [more] link on the examples header, like the syntax help link? (I'm quite pleased with how that turned out)
--Qazaaq 21:28, 25 April 2009 (UTC)

I think this is quite a good idea. The more examples available to a user, the more material there is to learn from, and that is always a good thing. I removed Maran's example from the IsInInterior page because I thought it didn't fit the style of other examples on the Wiki, and was therefore inconsistent, not because it was incorrect.
However, I'm not sure if extended examples will really be required for condition functions (like IsInInterior). Condition functions basically all work in the same way, so perhaps extended examples of condition functions should be more general instead of being specific to each condition function.
-- Cipscis 05:04, 26 April 2009 (UTC)

"Condition functions basically all work in the same way" -- this is exactly why I'm not so hot on the idea of prevalent semantic examples. Leave that to tutorials, IMO. If users need more examples... Fallout3.esm provides plenty. Particularly complicated functions, especially when added by FOSE, those deserve more detailed functions, IMO. Taglag on the CS wiki seemed to be requesting complete scripts using every function... that just does not seem necessary. Certainly more than one line is acceptable, but if it was getting beyond five or six I'd have to question how much that example focuses on the function itself.

Just my 2¢.

DragoonWraith · talk · 06:30, 26 April 2009 (UTC)

In most language references, it's nicer to have a few brief examples showing the full range of possible use cases, than a single lengthy example showing the context in which it might be used. The one exception I can think of is open/read/close, which tend to be shown in an example together I'd argue for not to delete lengthy examples merely because of style: instead to reformat them into the correct style.

However, if someone were to key in a longer example, I certainly wouldn't delete it as unfitting: if it were mammoth, I'd move it off to its own page, but I have strong reservations against deleting any useful user-created content: it's inefficient to waste the work, and it dissuades the editor from creating more pages, if they see swathes of work they spent a long time on being scorned and trashed rather than built on. There are few enough contributing editors as it is. DewiMorgan 13:08, 26 April 2009 (UTC)

Fair enough. Short examples will do, tutorials and Fallout3.esm can provide additional examples. But what are we going to do with examples that are unsuitable for the article page? Deleting may send out the wrong signal, as DewiMorgan mentioned, and reformatting isn't always an option. We could make a "style needs work" tag for those page, but I don't think any form of reformatting could have made the example on the IsInInterior page useful.

--Qazaaq 17:45, 26 April 2009 (UTC)

Could simply put it on a IsInInterior/More Examples page...

DragoonWraith · talk · 17:41, 27 April 2009 (UTC)