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

[The_J]

Any chance that you try it with another browser? At least IE should be installed as default (...unless your system is not older than 2 years, or so, I know).

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".

...er...but where? All the links are red, so there's nowhere additional info .

Oh, and totally minor thing: When I recently wanted to write "infos", someone corrected me that "information" does not have a plural in English.

 

[DonQuiche]

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.

Thank you. I've been able to reproduce it and I will fix that for sure.

Any chance that you try it with another browser? At least IE should be installed as default (...unless your system is not older than 2 years, or so, I know).

Was this for me or Pazyryk? As for him, he doesn't need to, it's up to me to make it compatible with all common browsers. As for me I have Firefox, IE, Google and Opera installed on my computer and I will make sure they're all fine with the modiki.

...er...but where? All the links are red, so there's nowhere additional info .

Because I do not send 100MB of data and one thousand queries anytime I test a new iteration.
I update one page at a time and focus on five or six of them. Once everything is ready I will order my bot to generate every page and there won't be any link left in red on the modiki.

Oh, and totally minor thing: When I recently wanted to write "infos", someone corrected me that "information" does not have a plural in English.

Thank you for pointing that, here is one less wrong habit!

 

[The_J]

Thank you. I've been able to reproduce it and I will fix that for sure.

[...]

Was this for me or Pazyryk? As for him, he doesn't need to, it's up to me to make it compatible with all common browsers. As for me I have Firefox, IE, Google and Opera installed on my computer and I will make sure they're all fine with the modiki.

Was meant for him. Thought it was a user related issue.
But what is now the problem? (I assume you know it now)

Because I do not send 100MB of data and one thousand queries anytime I test a new iteration.

Ah, okay, sorry.
Was just a bit confusing right now. If it happens like you plan it, then it should be fine as it is.

 

[DonQuiche]

Was meant for him. Thought it was a user related issue.
But what is now the problem? (I assume you know it now)

I didn't investigate it yet. But for something to appear in the TOC it must be a header (<h1>, <h2>, etc) so every function link is actually a header. But headers are styled by default with larger font sizes so I had to set "font-size" to 100%. Add to that the fact that <code>, <hN>, <span> and <a> markups are nested together (the latter two are inserted by mediawiki) and you get a nice little edge case for a browser's rendering engine. Or maybe it's the browser's default stylesheet. Or maybe some CSS property now obsolete. Or... Damn, it's html, you know how bad it is!


EDIT: Nevermind. Actually the whole Chrome rendering is catastrophic. No bold for standard types (int, string, etc), cells do not take up the whole column width, no "edit" link on sections, ridiculously small font for everything, etc.
Opera, IE and Firefox all have the same rendering though.

EDIT: Found it!
Seems like it should also occur in Safari since this is a webkit problem. This bug report also exposes a way to fix it, I added it to the first entry in TestC. I will ask Daenej to add this in the wiki's css sheet.

 

[The_J]

But the report says "Status: Fixed" .

But well, the other structure of the TOC should have already solved the problem nevertheless, shouldn't it?

 

[DonQuiche]

But the report says "Status: Fixed" .

If you read the details, it's not clear. For the start, the issue was about a confusion between the "monospace" font family and the "monospace" font. Webkits considers that it's the font name (a non-vector font with very small characters), while Firefox, IE and Opera considers it's the font family and uses another font from the monospace family instead: Courier New. So it's not really a bug and more like one possible correct answer that produces a bad result, and the webkit dev who handled it was reluctant to modify their behavior.

As of whether it was "fixed" or not in Webkit and why Chrome still has that behavior, I do not know. Anyway, it's the same issue for sure, that can be solved for example by setting "font-family: monospace, monospace" (webkit then considers that the former is the font family and the latter the font name, which results in Courier New)

But well, the other structure of the TOC should have already solved the problem nevertheless, shouldn't it?

Not sure about what you mean. If you mean that the header markup within the code markup should anyway override the font family setting, the answer is no: the only tags with font family overrides are tt, pre, samp and code. Hence why all texts within "pre" and "code" markups on the wiki (and many other sites) display that behavior.

Now, as a bonus, I also asked Deanej to set Consolas the preferred font (the one used by Visual Studio and others) for those markups, it looks so much better than Courier New and its serifs. And also to enlarge it by 10%, so it harmonizes better with the rest of the text. Looking at TestC and AcquireCity you will see it.

 

[The_J]

I thought the problem was caused by all the function names being headings, which is not anymore the case with the other TOC. That's what I meant.
But well, not really important, since you found out how to fix it.

for the forensics work .

 

[DonQuiche]

Events are now supported.
Here are the results. Do not pay attention to the layout, there are a few functions mixed with events. So, for the Events, GameEvents and LuaEvents pages I will create one section for events (with alphabetical subsections), and another one section for the few methods (without any subsection). There are also things like "playerIDID", they will be removed.
GameEvents and Events.

So I guess I now have all the business and logic parts implemented (aside of a few minor tricks and refactoring but it's no big deal). What's left now is polishing the pages but this requires the wiki to support images upload. I will contact Ainwood to see if I can be of any help. Once all of that is done I will submit three models to a poll, and maybe create subsidiary polls for side questions (for example the pseudo-types naming convention). Can we have multiple polls in the same thread? Anyway I would like the voting session to be quite short. Despite of that, should the number of votes be too low or the results close, I may not commit to them.

After that, well... The pages will all be created and there will be a short beta-test phase where I will allow the bot to override the content at anytime. During this phase the old API portal will coexist with the new one. It will also be the time for a few manual pages creation.


@TheJ
The header problem was my first guess but in the end it wasn't a problem.

 

[DonQuiche]

Deanej just told me he modified the CSS to fix the Chrome problem. Enjoy.

Right now I am continuing the development on a local copy of mediawiki. It allows me to use icons right away, among other benefits. As a result you won't see live updates anymore but here is a preview.

 

[Pazyryk]

That looks great! And thanks for tracking down my problem (it's fixed now on the old test pages).

 

[DonQuiche]

A small status update.

On the wiki side the images upload is still not fixed unfortunately, hence why I did not upload anything. However two new extensions have been installed, one to allow more powerful templates to make text edition easier (things like {{Type5|PlayerID}} to automatically create the links and such, and similar templates for icons with proper tooltips, etc) and another extension that provide a markup for automatic syntax highlighting with LUA support, which is really nice!

Now, on my side, I had a final version in hands. But since I couldn't use it yet, I decided to use the time before the images upload is fixed to modify the LUA processsor. Before it was made of regex-like searches (more complicated than this actually since it was also simplifying code on the fly) focused on functions calls and declarations. However the new one is a regular LR processor that parses LUA exactly and understand every rule of the language, from operators to statements. I managed to skip the AST and pseudo-AST steps (that would mean to define plenty of objects, deal with objects graphs, etc) since functions and such can be treated on the fly while being aware of the types of the arguments they get and what the caller expects.

What's the point? To improve the type inference and provide better code samples. There were some situations where the previous LUA processor was not able to correctly infer some types while the new processor should be able to resolve everything as long as it's used somewhere in the code.

However, on the bad side, I think I will drop the poll. I now have a good idea of what works, what does not work, and the pros and cons of every design issue, so the model I designed is really the best solution imho. Some may disagree but I think a few would do should they have spend hours working on it and experiencing it. Besides I am too afraid that many people would vote without taking the time to investigate things a bit and would skip the remarks I would provide to draw their attention on important but not obvious points.


PS: I would like to hear your opinions on the method versus function terminology in the LUA context. There are three cases to cover: global functions, static methods and instance methods. Do you think static methods should be called functions instead since they do not take a "this" reference? Or do you think we should just call everything "function" for beginners?

 

[The_J]

I think I lack the LUA knowledge to give any reasonable answer.

However, on the bad side, I think I will drop the poll. I now have a good idea of what works, what does not work, and the pros and cons of every design issue, so the model I designed is really the best solution imho.

Whatever works best .

 

[Pazyryk]

PS: I would like to hear your opinions on the method versus function terminology in the LUA context. There are three cases to cover: global functions, static methods and instance methods. Do you think static methods should be called functions instead since they do not take a "this" reference? Or do you think we should just call everything "function" for beginners?

Nice to move the beginners (including myself) toward the right language on these things. Helps us down the road in other contexts. (May also help in this case to know when to use a period and when to use a colon.)

On the other points in your post, I vote (though my vote wasn't requested) for whatever gets this up the soonest. I've already been using some of your test pages. (I assume that it can be updated dynamically as you develop better processor gizmos, or if we get some new code to run the gizmos on?)

 

[DonQuiche]

Nice to move the beginners (including myself) toward the right language on these things. Helps us down the road in other contexts. (May also help in this case to know when to use a period and when to use a colon.)

I was interested by that point of view and how you want to get the exact terms that may help in other languages. So I will stick to how the word is used in statically typed languages since it is a realm where everything is cleaner and more strictly defined.

That means I would use method for any function that belongs to a type, regardless of whether it has a "this" argument (and so regardless of whether it needs a colon or a dot). So three categories : "global functions" (do not belong to a type), "static methods" (belong to a type, only requires a dot) and "instance methods" (belong to a type, requires a colon). This is the terminology used in C++, Java, Dotnet, etc. I will add a brief sentence at the start of every section.

On the other points in your post, I vote (though my vote wasn't requested) for whatever gets this up the soonest.

As I said, the bot was already over. Everything we talked about before is done, from UI Elements to pseudo-types, global functions, thematic categories, etc, etc, etc. I am polishing things up but if we could upload images, the wiki would already be online. The only thing that delays me is the images upload and, well, and now that I started some big changes I will finish them but it's a matter of a few days. Basically, every week I improve the bot but it will never be perfect and it's already very good. So as soon as the images upload problem is fixed, I will wrap things up and upload everything.

I assume that it can be updated dynamically as you develop better processor gizmos, or if we get some new code to run the gizmos on?)

Nope.
Because my bot overwrites the pages, which means any addition from users would be lost. Technically I could write an importation process dedicated to this new wiki, with a merge algotihm, but it's too much work and there is little purpose to do so since the API is stable. So there will be a beta period with big red warnings and everything at the end of this beta will be overwritten. After that the bot will never be used again and users will be able to modify the wiki's pages as things should be on a wiki.


PS: Here is a .mht version (archive with html, css, etc - readable by Opera and IE) of the home page so that you can see how far things are. Every page mentioned on the home page (aside of the hand-written articles I can do later) is 100% done. All links are blue for me.

 

[DonQuiche]

The new LUA processor is over and it works like a charm. Aside of the functions that are never encountered in the source code, consider that about every function is documented with proper types and pseudo-types.

Now, while we wait for the images upload is fixed, I am thinking about writing a rudimentary disassembler to autodocument the functions that are never used. I do not know if I will have the time but it sounds interesting!

 

[DonQuiche]

Better code samples. Thanks to the new LUA processor, the bot is now aware of the relations between the different lines of code. As a result, when it extract examples from the LUA source files, it does more than just select one line, it also includes the lines where the involved variables were defined. Add syntax colorization over this and you get nice examples like this one:

 

[DonQuiche]

I am still waiting for the images upload to be fixed. Meanwhile here are some screenshots...

Home page
Global functions
Common UI Properties
Category: Civ5 Happiness API (thematic category example)

BeliefType (identifier example)
PopupInfo (structure example)
Area (object example)
InstanceManager (lua object example)
Image (UI Element example)

Player.GetUnitByID (method example)

 

[The_J]

Looks very nice .

 

[Pazyryk]

Wow! That's an amazing wiki you have created there. Just fantastic. I can't wait to see it up and running. (Who can I harass or bribe to get the images upload fixed asap?)

 

[DonQuiche]

Thanks to both of you.
On one side the fact that this problem has not been fixed yet makes me anxious, I am starting to doubt that I will ever be able to upload that baby on CivFanatics and I am considering whether I will have to fire yet another wiki (oh crap! we already have two). On the other side I do not urge things yet because although the result is already great, there are still a few things I want to check, to improve and such.

Some examples:
* The lua/UI parser works like a charm (clean, fast, etc) but the type inference that comes after that could be improved. Its main problem is that it does not take into account includes and I used hacks instead. As a result I had bad surprises and the inference efficiency is far more decreased than I expected it to be. I need to implement my own VFS and include system.
* This new system will also offer stronger guarantees that no method or type is forgotten since every namespace will be resolved. I may also identify a few structures I was not aware of. The idea is to make sure that the list is complete.
* I am bothered by the grid/hex coordinate systems. I considered types but that could be ugly. Instead I now want to rename every "x" and "y" arguments to "hexX" and "gridX" depending on the coordinate system they are expressed in.
* I didn't show them but some pages include manually written parts (the system looks for text files in a certain folder and include them in the generated pages), I need to write a few more (GameInfos mainly).
* There is the binary parser I talked about before.