[Poll] Which style for the LUA reference on the wiki?

[The_J]

That goes too fast for me (but my opinion is not really important).

Test10 looks like what I had in mind (don't like the formatting, but that's unimportant too ), but Test4 is also okay. But I'd doubt if most of the pages would ever be created, because like Pazyryk said, they'll probably not require any explanation.


@buildingType/ID/Pseudo types: I'd keep it like it is, just to avoid confusion.
Civ4 Python had the same, and you get very good used to it.
If you want to make that stuff more clear for the beginners, then I'd say a list of the pseudo types at the beginning of the wiki page and a general explanation might maybe be the easiest thing.

 

[DonQuiche]

I guess that's fine. I just want some kind of quick visual cue that the method does what it appears to do and I need not look further, which is the case for 95% of them.

Now we could also take something like test4 and test10 and only include a one-line description sometimes. Or put it on the tooltip of an icon on the right. But I think that given the scarcity of detailed informations, it's more important to focus on an easy-to-browse model even if it means you have to open a new page one out of thousand times.

The icons idea sounds great though. I could imagine two important icons:
(!) Known or suspected not to work.
(*) Non-intuitive usage.

Imho rather than keeping broken functions, we should move them to a deprecated section at the bottom. But the warning about non-intuitive is good, so maybe something like this for icons and their tooltips:
* Speech: A one-line description of the function (if we don't write this comment below the function)
* Information: this function has detailed informations on its page
* Warning: there is something you should know before you use this function, see its page.

The latter is somewhat subjective, but I doubt it would be overly used in a bad way. An example would be Map.Areas(), which you might guess iterates over either pArea or iArea (the value returned by plot:GetArea()), but does neither.

Are you sure it does not? I think I already used it. Maybe your areas weren't initialized yet (through recalculateareas).

I like that you are consistently using "buildingID" to mean row ID (int) and "buildingType" to mean row Type (string). However, how are you handling unit object index (the value returned by unit:GetID())? I always use unitID for the table row and unitIndex for the object index, but Firaxis freely mixes the two, making it impossible to derive a standard that is consistent with the method names.

My plan is to use unitIndex and unitID the same way you do. It does not matter if the APi is not correct, my process includes all sort of corrections, some being automated and some being manual (either I modify the local copy of the 2k wiki, either I edit a patch file where I provide replacements for the functions signatures, typically for the G&K ones).

That goes too fast for me (but my opinion is not really important).

Even if you do not mod for civ5, it's good to have one more modder's opinion.

Test10 looks like what I had in mind (don't like the formatting, but that's unimportant too )

I do not like it either of if you hame some suggestion, it's welcome.

But I'd doubt if most of the pages would ever be created, because like Pazyryk said, they'll probably not require any explanation.

As I said, I do not like that either but I think it's the easier way for all the reasons I mentioned. And the thematic and global indexes are worth it, aren't they?

@buildingType/ID/Pseudo types: I'd keep it like it is, just to avoid confusion.
Civ4 Python had the same, and you get very good used to it.
If you want to make that stuff more clear for the beginners, then I'd say a list of the pseudo types at the beginning of the wiki page and a general explanation might maybe be the easiest thing.

You mean I should keep the Firaxis type names?
Anyway, yes, I intend to provide a list of pseudo-types.

 

[Pazyryk]

OK, it all looks good to me (except for the ugly formating).

Are you sure it does not? I think I already used it. Maybe your areas weren't initialized yet (through recalculateareas).

Spoiler :

It's during a game, but I never used recaculateareas (should I?).

for area in Map.Areas() do print(area) end

--this prints integers 1 through 29 (not area objects, which is different then other similar iterators)

for iPlot = 0, Map.GetNumPlots() - 1 do print(Map.GetPlotByIndex(iPlot):GetArea()) end

--this prints integers too, but they are like 573441, 688143, 745494, etc.

 

[The_J]

Now we could also take something like test4 and test10 and only include a one-line description sometimes. Or put it on the tooltip of an icon on the right. But I think that given the scarcity of detailed informations, it's more important to focus on an easy-to-browse model even if it means you have to open a new page one out of thousand times.

Sounds good.

Imho rather than keeping broken functions, we should move them to a deprecated section at the bottom. But the warning about non-intuitive is good, so maybe something like this for icons and their tooltips:
* Speech: A one-line description of the function (if we don't write this comment below the function)
* Information: this function has detailed informations on its page
* Warning: there is something you should know before you use this function, see its page.

Sounds also good (if the further above mentioned attempt is not done).

I do not like it either of if you hame some suggestion, it's welcome.

Design is one of my weak spots, so sadly I don't have any suggestions .

As I said, I do not like that either but I think it's the easier way for all the reasons I mentioned. And the thematic and global indexes are worth it, aren't they?

I cannot disagree .

You mean I should keep the Firaxis type names?
Anyway, yes, I intend to provide a list of pseudo-types.

Yup, that.
Avoids confusion, because it might split the community, and then it will get more complicated to read other people's code.
(...er...in Civ4 we often use the firaxis type names as variable names, and most people stick to that)

 

[DonQuiche]

@Pazyryk
[/quote]You must use "for i, pArea in Map.Areas()"
And (Re)CalculateAreas() is mostly useful during map generation. You should use it whenever you modify the terrain itself (change water to land, make a terrain passable/impassable, etc). There is no point outside of that.[/quote]

@The_J
This is interesting, I would like to get more opinions on the data types. Because, sure, we get used to them and it can be slightly confusing to see something new at first. Still, the 2k documentation confused me like hell when I began: at first I though those were documentation errors and I persisted writing functions that would get types instead of ID unless I admitted that whenever a function says "type" it's actually "id". Which is totally nuts.

Now, indeed, the trouble is that the LUA code from Firaxis and from many modders use the "types" naming convention. I don't know whether the wiki would help clarify that or make it even more confusing.


Update:
* TestA: compact model
* TestC: extensive model

Signatures in TestA are currently more complete than in TestC, they benefit from a minimalist LUA parser I wrote to scan the vanilla LUA files, although there are many functions are never used anywhere. This parser will also let me include in a function's page the list of files where it is used, along with examples collected from those files. That, however, cause a problem: if we choose something like TestC, should all the infos be displayed in TestC, or should we keep an additional function's page? With the former the page would be even longer, while with the latter contributors would have to edit both the giant TestC page and the function's page.

Alos, should I create a multi-column TOC for TestC ?

PS: I never talk about categorization because it can be done with all models. But I have no idea on how to make it good. Very small categories like this are not convenient imho and just two categories (setters/getters) already have their cons, although small. I tend to think it would be better to not use categorization in the object's page and only use separate categories page where functions from all objects would be automatically listed (a "resources" category page that would include all functions related from resources whatever the object they're from). And maybe use alphabetical sections in objects pages with a lot of functions (1651 methods in player? WTH?!)

 

[The_J]

TestC looks good.
I think separate pages for the details would be better.
Multi-column TOC would also look better.

@categorizations:
I agree, don't think categories within the objects page are needed. Alphabetical should be enough .
For the big categories, maybe make a separation into the used/unused functions (assuming that unused might be either not useful, not functional, or usage is unknown). Not sure if that might increase the overview, but it might be worth an attempt.

Oh, and a big "" for you .

 

[DonQuiche]

For the big categories, maybe make a separation into the used/unused functions (assuming that unused might be either not useful, not functional, or usage is unknown). Not sure if that might increase the overview, but it might be worth an attempt.

I agree there might be something to do with those "unused" functions. Recently I focused on the detection of vanilla/G&K support, I will try to incorporate those functions in the listings and see how it looks, how many functions there are, etc. After that I will decide whether I put those unused functions in a distinct section, or grayed out (may not be possible to change a link's color though), etc.

I am also parsing the exe and dll files in order to detect non-existent functions (and I guess it may be used the other way around, to list all methods on those objects that cannot be scanned, like Network or GameEvents). Those missing functions will just be removed and I guess there are plenty.

On another topic, I improved the LUA code parser and the program now also scans the UI elements with their functions and XML properties. And I also have to produce a new listing model that uses collapsing boxes (with a "hide"/"show" pseudo-link hooked in JS), thanks to Daenej. And Ainwood is working on restoring the images upload.

 

[The_J]

Hopefully that all works like intended, because it sounds like a good plan to proceed like that .

 

[DonQuiche]

Hopefully that all works like intended

But it *does* work.
TestA fully benefits from the improved parser and type inference, with very few signatures still unknown (because they are never used). It also emphasizes alphabetical categories (trivial) and the vanilla/g&k flags on the left (I use text since we do not have icons yet).
TestFunc with all the occurrences detected in the LUA code.
TestType with the "referencing methods" section working properly.

Regarding the lua parser and type inference, I think there are no false matches left. And while it's probable that a few more cases can still be managed, what's left is mostly unguessable unless one tries to actually use those functions, or requires a human edition anyway because some functions names are too complex for a reasonable algorithm (I am not planning to write a linguistic AI).

So what is left is mostly a formatting/layout matter and those ones are quite trivial.


PS: From what I see now that things are fleshed out (do you all agree ?)...
* Alphabetical categories are the way to go.
* Few functions really exist and are never used. So I think they should stay in the listings because many of them should actually work.
* I also don't think we should remove the vanilla-only functions, although there is quite a bunch of them.

 

[DonQuiche]

And here is TestB with collapsing boxes (look at the [show] link on the right of AddNotification for example). If javascript is disabled, TestB looks like TestC.

Regarding the multi-column TOC, while I could create one manually, it would not be automatically updated anymore if a user was adding a new section, so I think it's actually a bad idea. TestB and TestC already have an important con for editors: they would need to edit everything twice (the listing and the the function page) and the listing is also quite bothersome to edit manually. I would prefer to not add one more burden.

Now, I think the alphabetical sections are actually enough, don't you think so?

 

[The_J]

I agree on everything.
The pages also look good IMHO.
Not sure though what the [c] "this page has additional info" means.

What about another...er...tag for unused functions? Because you're right, doesn't make sense to separate them.

Agree also on the multi-column TOC. If it's a real barrier for new users, then it shouldn't be done. (but still a bit )

 

[Pazyryk]

I'm happy with straight alphabetical.

On formatting: can you at least use a bigger font on the down-page section? (Yeah, ...time for me to get some bifocals.)

Can you mark methods that are vanilla-only and G&K-only? (icon or whatever)

I'd love to see a preview of those Network and GameEvents methods...

 

[DonQuiche]

Not sure though what the [c] "this page has additional info" means.

Basically it means that there are either comments, either regarding parameters or the function description itself. Once image uploads are restored, I will use a "star" icon instead. Now I guess I could find a better tooltip. "This page has detailed comments"?

What about another...er...tag for unused functions? Because you're right, doesn't make sense to separate them.

This may be a good idea.

Agree also on the multi-column TOC. If it's a real barrier for new users, then it shouldn't be done. (but still a bit )

Now I wonder: do we even need functions to be displayed in the TOC? I really think the alphabetical sections and condensed listing make useless to have a three kilometers-long TOC, at least with A and B. And maybe even C?

On formatting: can you at least use a bigger font on the down-page section? (Yeah, ...time for me to get some bifocals.)

Well, two problems with that:
* Wikis are about content, not about formatting. While some html tags are allowed, and I abuse them, I would need to do it even more and write everything in html, which would make editing even more bothersome.
* It would be a bit clumsy to have some pages in font 14 and some others in font 12. The current font size is the same as on any other website so I think you should increase your DPI setting or configure your browser.

Can you mark methods that are vanilla-only and G&K-only? (icon or whatever)

This has been done in TestA. In the end I intend to use those tags on all three models (and replace them with icons asap).

I'd love to see a preview of those Network and GameEvents methods...

It's too early for GameEvents (the LUA parser do not yet know how to deal with forms like identifier.identifier.add(function)) and this is one of the few pages that will require a heavy manual editing anyway.
However, regarding Network, here is TestC2 where the LUA parser shows its power (there was no doc at all on the 2k wiki for this object). Of course many arguments' types could not be inferred (again, this is a rudimentary parser, not a full-fledged SSA analyzer) but since the functions' pages list every occurrence in the code, it will be pretty easy for a human to figure out those types.

 

[Pazyryk]

TestC2 checks out exactly with my manually gotten list here. Great! (my thread has some args that may help for manual curation of these)

* It would be a bit clumsy to have some pages in font 14 and some others in font 12. The current font size is the same as on any other website so I think you should increase your DPI setting or configure your browser.

Look, I know it's time to find the Old Man settings for my browser, but I can see quite well when I put my face up to the screen. The TOC is in Arial 9, and the down-page details are in Verdana 8. For whatever reason, the first is very easy on the eye, but the second appears pixelated and has a funny off-white background color. Is this really a Wiki default? (The 2K wiki is exactly the same for the TOC, but uses Arial 10 for the method signature and description text)

 

[DonQuiche]

TestC2 checks out exactly with my manually gotten list here. Great! (my thread has some args that may help for manual curation of these)

Thank you, it's a good thing to know.

Look, I know it's time to find the Old Man settings for my browser, but I can see quite well when I put my face up to the screen. The TOC is in Arial 9, and the down-page details are in Verdana 8. For whatever reason, the first is very easy on the eye, but the second appears pixelated and has a funny off-white background color. Is this really a Wiki default? (The 2K wiki is exactly the same for the TOC, but uses Arial 10 for the method signature and description text)

Ah! Unfortunately those ones are per-wiki settings and they can only be changed by admins, so you would need to ask Deanej. It's not possible to include css declarations in regular wiki pages and since the TOC and footer are automatically generated...


Small update: UI elements now have their pages too! See TestUIElement for GridButton.

 

[The_J]

Basically it means that there are either comments, either regarding parameters or the function description itself. Once image uploads are restored, I will use a "star" icon instead. Now I guess I could find a better tooltip. "This page has detailed comments"?

So there are comments in the LUA files?
If so, then this should be spelled out, because first I sat there and looked around, thinking "where is here more info? Can't see it."

Now I wonder: do we even need functions to be displayed in the TOC? I really think the alphabetical sections and condensed listing make useless to have a three kilometers-long TOC, at least with A and B. And maybe even C?

mmhh...has a point, you're probably right.

Look, I know it's time to find the Old Man settings for my browser,

Crtl and + zooms in (at least in FF).

but I can see quite well when I put my face up to the screen. The TOC is in Arial 9, and the down-page details are in Verdana 8. For whatever reason, the first is very easy on the eye, but the second appears pixelated and has a funny off-white background color.

mmhh...screenshot?
Do not really understand what you see.

 

[Pazyryk]

Overall layout (I'm fine with the TOC):

Spoiler :

Closeup (makes me nostalgic for my Commodore 64...):

OK, I didn't notice before but the off-white is just the forum background. But the wiki uses white background, doesn't it? Is the pixelation due to some limitation on my side? (If so, it's showing up on two very different computers, albeit both using Chrome.)

 

[The_J]

Could be a browser problem, or maybe the screen resolution .
That's it for me with FF14 on 1024*768:

Spoiler :

 

[DonQuiche]

So there are comments in the LUA files?
If so, then this should be spelled out, because first I sat there and looked around, thinking "where is here more info? Can't see it."

There are comments in the function's page on the modiki, not in the LUA source files from the games. I guess "this page" should be replaced by "this function's article/page has detailed comments".

@Pazyryk
Wow! No, this is not normal. Stupid html pseudo-standard. Which browser do you use please?

 

[Pazyryk]

Wow! No, this is not normal. Stupid html pseudo-standard. Which browser do you use please?

Chrome. It's pretty rare now to see web pages that don't work well with it (used to a few years ago). I haven't changed any browser settings, and it's two different computers from different os eras.