Wiki Updates (masochism?)

I'd prefer to keep ZLib documentation on the forum rather than the Wiki. If you'd like to use examples using ZLib functions (rather than examples from ZLib functions), then make sure to use include <zlib.ash> at the top of the example, and make "zlib.ash" link to the ZLib thread. Or the Wiki page for a ZLib function could be a mere placeholder, pointing to the forum thread. As usual, I'll go with whatever the community decides. It does seem that using ZLib functions in examples would be confusing to scripting newcomers, though.

A good way to include ZLib functions might be in the "See Also" section. For example, the page for change_mcd() could include a "See Also: auto_mcd() (ZLib) -- adjusts MCD automatically for optimum stat gains". Then, there would be a link to the ZLib forum thread. ZLib has already accomplished tasks that a lot of scripters would like to accomplish, plus it has been debugged and improved by the community at large, so it seems that omitting ZLib entirely from the Wiki might be the opposite of helpful.

Wondering how errors will fit in. Originally I'd wanted to include all possible abort errors with each function. This leads easily to the idea of having a page for each error, describing what went wrong and which functions can generate that error. Then, if a user/scripter encounters an error (mafia's error messages are often fairly terse -- they are correct and concise, but can confuse newbies), they can locate the error on the Wiki to track down the problem.

heeheehee said:

Also wrong. #8A8A8A is darker than #AAAAAA. Heh. Darkened anyways.

The light blue-grey isn't actually part of the syntax-highlighting, but I'll remove it, if it's really bothering you. Other fixes have been made, but the #00FFFF is a bit... bright. Also removed the greening of the records (I realized that was a leftover from methods in Java, where I jacked the template, mostly).

Click to expand...

Heh, that's what I get for trying to make such calls at 1am. Actual color selections I suggested last night are bound to be awful, as 1) I was too tired to be doing that and 2) Looking at a color chart isn't the same as looking at text in said color on a white background.

Go ahead and tweak what's easy, but that light blue isn't a huge deal; if it turns out to be a pain to change, no worry. Just minor suggestions at this point, really. Can't wait to see the next iteration!

zarqon said:

I'd prefer to keep ZLib documentation on the forum rather than the Wiki. If you'd like to use examples using ZLib functions (rather than examples from ZLib functions), then make sure to use include <zlib.ash> at the top of the example, and make "zlib.ash" link to the ZLib thread. Or the Wiki page for a ZLib function could be a mere placeholder, pointing to the forum thread. As usual, I'll go with whatever the community decides. It does seem that using ZLib functions in examples would be confusing to scripting newcomers, though.

Click to expand...

It's a tough call at this point. There are libraries for many programming languages that some people often forget aren't part of the core language itself, and in some ways ZLib is close to that for ash.

zarqon said:

A good way to include ZLib functions might be in the "See Also" section. For example, the page for change_mcd() could include a "See Also: auto_mcd() (ZLib) -- adjusts MCD automatically for optimum stat gains". Then, there would be a link to the ZLib forum thread. ZLib has already accomplished tasks that a lot of scripters would like to accomplish, plus it has been debugged and improved by the community at large, so it seems that omitting ZLib entirely from the Wiki might be the opposite of helpful.

Click to expand...

Yeah, again, tough call. Not mentioning ZLib anywhere just leads to the whole "reinventing the wheel" dilema; integrating it too tightly leads to the whole "Why won't this *#$% function work" dilema. In my personal opinion, I'd like to eventually have the ZLib functions on the wiki, in the form of page name = "vprint (zlib)" or similar. These pages would NOT be linked to from main category pages, but rather from a ZLib page that made it very clear at the top of the page that said functions were NOT part of KoLmafia's core, and what exactly was required to use them. This page would, of course, prominently link to your forum thread.

The ZLib function pages, if used, would also prominently mention -- probably before the function syntax, even -- that they are part of an external library, not the core of KoLmafia, with a reference to the ZLib page.

As far as "See Also" goes, I think I may add in another "See Also" type section specifically for external functions such as those in ZLib. Again, with prominent warnings yada yada.

In case you wonder why I seem so in favor of having individual pages for your functions: search results are much more reliable when the searched-for term is a page name (at least on a wiki). If one searches for "vprint," and the only uses are in some sample code, it could still be quite confusing to someone searching for said function. If there is a "vprint (zlib)" page, that will show up as (likely) the first search result, and better guide the new user towards what is required to use said function.

zarqon said:

Wondering how errors will fit in. Originally I'd wanted to include all possible abort errors with each function. This leads easily to the idea of having a page for each error, describing what went wrong and which functions can generate that error. Then, if a user/scripter encounters an error (mafia's error messages are often fairly terse -- they are correct and concise, but can confuse newbies), they can locate the error on the Wiki to track down the problem.

Click to expand...

That's a very good idea. If you'd like to put together a list of errors and how they can be generated, it would prove very useful. I've got a pretty good handle on templates & wiki editing now, if I do say so myself (and I do, modesty doesn't work for me early in the morning ). Good places to put such info would be in this thread, or over on my Talk Page on the wiki.

Also, my User Page on the wiki has a few different ways in which we could reference function pages from their category pages, in case anyone would like to vote. The first item is currently in use, but it's all in templates and easy to change to any of the displayed options. I do want to keep that general syntax though; I'd prefer that category pages list the functions the same way as "ashref" does to avoid confusion for newbies.

FWIW, I vote for initially making the wiki only include ash documentation. Furthermore all code examples should run without anything but Kolmafia. Thus I would not document ZLib on the wiki and I would not have any code examples that required me to include zlib.ash in order for them to work.

Not that either is likely, but what happens if zarqon stops maintaining zlib or zlib functionality is superseded by functions embedded in the language?

There are precedents from other languages where external packages are so popular that they are documented as if they were part of the language but there are also precedents where the documentation is separate and external. When the ash only portion was completed and generally satisfactory the decision could be reconsidered but for the moment I would ignore zlib on the wiki unless there was a discussion that linked to forum based documentation.

fronobulax said:

When the ash only portion was completed and generally satisfactory the decision could be reconsidered but for the moment I would ignore zlib on the wiki unless there was a discussion that linked to forum based documentation.

Click to expand...

For sure; I don't intend to seriously think about it until such point as all of the currently known functions have at least some documentation, and other major parts of the wiki-cleanup project are taken care of.

At such time, I'll play around with things and see how it goes. My main goal is to make things as easy as possible on the user trying to research functions, so I'd be happy to do the bare-minimum that allows said user to at least find a reference to the forum thread when searching for ZLib functions. I'm strongly in favor of that point, but for anything beyond that, I'm happy to respect zarqon's preferences. (Not meaning to imply that I won't respect zarqon's wishes if he wants to keep ZLib off of the wiki entirely, but I get the impression that he at least agrees with having a minimal reference there, just in case.)

So... do you have all the architecture you want in place? Should we start making/updating function pages? Where would you prefer that casual contributors (like myself) focus their efforts (new pages, examples for old pages, etc.)?

aqualectrix said:

So... do you have all the architecture you want in place? Should we start making/updating function pages? Where would you prefer that casual contributors (like myself) focus their efforts (new pages, examples for old pages, etc.)?

Click to expand...

Excellent point! I went to the effort of writing up what's needed on the wiki, but forgot to mention it here. Doh. Please keep an eye on the Main Discussion Page for updated info on what's being worked on & what we need help with. Thanks!

StDoodle said:

Go ahead and tweak what's easy, but that light blue isn't a huge deal; if it turns out to be a pain to change, no worry. Just minor suggestions at this point, really. Can't wait to see the next iteration!

Click to expand...

I changed all that stuff last night (including the light blue), so if you had tossed a script into the parser, it should've reflected the changes (None of this takes more than like two minutes to edit). The only change I've made today was removing the coloring of numbers (they looked too much like the core ASH functions!) and symbols (negative integers looked a bit funny).

On a slightly related note, I started making a CLI-equivalent variant out of boredom. I suppose that my ultimate goal would be to link the two together (what with cli_execute() and ash/ashq/<inline-ash-script>. I'll upload that as well -- to check it out, just change the language field to "cli" and input a CLI script. This obviously isn't very high priority on my end or probably yours, as CLI scripting is very minor. I just think it'd be really cool to have.

It seems the main reason for wanting to include ZLib functions on the Wiki is that they are employed by quite a few scripts, and if they are not searchable on the Wiki, scripting newcomers will be flummoxed. Contrariwise, ZLib is a fine example of ASH in use but isn't part of ASH itself, and including ZLib functions may cause those newcomers to be confused about what is ASH and what isn't -- resulting in such situations as bug reports (to the devs) about ZLib functions! I also have another, selfish motive -- I'm not going to edit the Wiki every time I edit ZLib. So -- I'm fine with your idea of a "placeholder" page giving a brief description of what the function does, but clearly stating that this is part of an external function library written in and for ASH, and linking to the forum thread. I think that would be a fine solution.

But, I also agree that we should focus on ASH itself first.

Re: errors. I think that eventually there should be room in the function template for possible errors generated. These will link automatically to the page for that error, which will also contain a list of all functions that can generate this error. The list would probably have to be generated over time, one message at a time -- I have no such list at the moment. Perhaps for starters we can make an error page, then incorporate them into function pages later.

Up to you whether to include "compile" errors as well as runtime errors. Don't think those are as tough to troubleshoot, though.

heeheehee said:

I changed all that stuff last night...

Click to expand...

Just checked it out; it's looking very nifty indeed. Thanks!

heeheehee said:

On a slightly related note, I started making a CLI-equivalent variant...

Click to expand...

Well, while ash is my primary goal, that's definitely on the to-do list. So it would certainly be neat to have such a thing ready to go when needed.

Also on the to-do list: a FAQ for mafia. Anyone else ever notice that a few of the same questions come up time & time again? (How do I re-apply stickers? What / where are daily builds?) I imagine if we could get a FAQ page on the wiki that represents the current use of KoLmafia, maybe one of us could just put it in our signature. Sure, we'd still get the question, but at least "look at my sig n00b" is quick to type.

Also also: I've archived the older talk on the main Discussion page on the wiki (no worries, it's linked to prominently). I've also added a section at the top with quick links to two category pages that automagically list pages we need extra help with.

zarqon said:

But, I also agree that we should focus on ASH itself first.

Click to expand...

Very much agree. Perhaps one day zlib will be worthy of a mention on the wiki. Meanwhile, it will be more exciting just to see the wiki properly explain ash.

In the meantime, I dream of a day where people will be given bats for correctly using the word "flummox" in a forum post.

zarqon said:

In the meantime, I dream of a day where people will be given bats for correctly using the word "flummox" in a forum post.

Click to expand...

That day has come.

heeheehee, the syntax highlighting is utterly killed after any ' in the text, such as in $location[Giant's Castle]. Is there a way to fix that?

I always script those as $location[giant castle] for precisely that reason -- my preferred editor's highlighting gets ruined by apostrophes in mafia data types.

It's been fixed for a while (see the testing grounds) -- StDoodle pointed this out a few pages back. Since I can't upload a new copy of ash.php, we have to wait until fewyn reuploads it. (I've provided a link to a copy of the source of ash.php on the testing grounds, as well, so now it's a simple matter of copy-pasting it to a text document and saving it as a PHP.)

zarqon said:

I always script those as $location[giant castle] for precisely that reason -- my preferred editor's highlighting gets ruined by apostrophes in mafia data types.

Click to expand...

Well, I'm doing the same on the wiki. I also changed a comment from "don't" to "do not". There are ways to work around it, but it would be better if it didn't have that problem. I might not be able to avoid a ' some day.

Edit: Ninja'ed by heeheehee.

heeheehee said:

It's been fixed for a while (see the testing grounds) -- StDoodle pointed this out a few pages back. Since I can't upload a new copy of ash.php, we have to wait until fewyn reuploads it. (I've provided a link to a copy of the source of ash.php on the testing grounds, as well, so now it's a simple matter of copy-pasting it to a text document and saving it as a PHP.)

Click to expand...

Ah. It's only a matter of time now then. Happy.

Bale said:

Ah. It's only a matter of time now then. Happy.

Click to expand...

Yup, and as such I wouldn't worry too much about it. While fewyn is going to be busy for the next week, it will get added eventually, so no worries. If some pages look odd for a week, it doesn't bother me as long as I know they'll fix themselves. Also -- and correct me if I'm wrong heeheehee -- but your latest version will automatically have recognized ash functions as links to their pages (in the short-name without parenthesis form), right? Ie adventures() will link to the page "adventures" correct? If this is so -- and awesome if it is, and works -- I'd like to avoid adding functions into the "See Also" part just because they're in a code sample. I'd rather save that for functions that have very similar behavior or are fundamentally linked. (Ie "adventure" and "adv1" or "my_inebriety" and "my_inebriety_limit")

Edit to clarify: By "if it is, and works" I mean to say if the wiki software doesn't do something somewhere else to break such functionality; not implying that you don't know what you're doing in any way.

Edit to add: 'nother thing that would be awesome to have on the wiki is a favicon (I use them for all my bookmarks, w/o text; except for the wiki & consumer's energy). A mini JH robot would be cool, if it could fit.

bumcheekcity said:

In short, here's how I think we should call the functions template:
....
The slight disadvantage to my method is that there's an upper limit to the number of arguments you can have. The advantage is that adding them is utterly trivial.

Click to expand...

The main difference between your method and mine (which, btw, is already being used on quite a few pages) is that mine supports multiple function call lines on one page, without having to retype the function name. Otherwise, minor cosmetic differences, for the most part. You should check it out! (http://wiki.kolmafia.us/index.php?title=Template:FunctionPage)

I've attached a .txt file of ASH functions written in a map form (for parsing). The format ("|" representing tab spaces) is:


Parameters are separated by commas and there is a trailing comma (the final parameter has a comma at the end). Of note are aggregate values (which give the return type followed by "[int]") and appearance_rates() which returns a float or a monster aggregate (I think?).

No idea if this is useful, but it's there if you want it. All data is taken straight from RuntimeLibrary.java.

StDoodle said:

Also -- and correct me if I'm wrong heeheehee -- but your latest version will automatically have recognized ash functions as links to their pages (in the short-name without parenthesis form), right?

Click to expand...

That'll have to be a modification of geshi.php (I think?), which I haven't gotten around to quite yet. The way I see it, I can either see if GeSHi plays nice with wiki markup (and just have it insert the double brackets as needed), or just have geshi.php generate the URLs. The second option is probably guaranteed to work, while the first is a bit iffy. But the second requires me to actually scan through 2k+ lines of code, so it'll take a while.