Wiki Updates (masochism?)

[StDoodle]

My point was that the Wiki should made to influence non-programmers to think like programmers...

I only agree up to a point; it should do so on the pages for the functions, themselves. It shouldn't go so far as to frustrate someone who doesn't type "visit_url()" into the search box, but rather "visit_url". As a test, I made a page for "test_function()" on the wiki (which will be deleted shortly). The default search, when "test_function" is entered in the search box, returns absolutely nothing. I think this goes beyond "encouraging people to think like a programmer" and more towards "mind-numbingly frustrating for the new user." Again, if the way wiki-search worked by default was different, this wouldn't be an issue & I'd be on the side of including the "()" in a page's title.

@StDoodle - Chin up. This is supposed to be fun for you. Please don't let it be otherwise

It mostly is, so I shall continue. I like a nice challenge, anyway, and being the "voice of the non-programmer" on a site such as this certainly fits the bill!

My focus on the parenthesis issue is strictly based upon finding things....Thus I hope my opinions are not offensive and recognize that I am not necessarily helping us towards the goal by expressing them.

Me too, and me too.

If a template is set up, may I ask that it is clear for a non-wiki expert to edit its content. Currently pages such as this look completely bizarre to me and I wouldn't have a clue what all the {}s mean.

Yeah, that's a result of trying to test out features that aren't currently implemented. I think bumcheekcity & I are in agreement that the template itself should contain most of the grunt work, such that when you make / edit a page to reference that template, all you have to do is fill out a couple of basic pieces of information.

Finally, may I ask for some sort of advice to be documented on what makes a good code example. In my head, simpler is better but some code on the wiki seems also to try and show off. For example, why does the function creatable_amount() require the user to know and understand what map constructs do? While it's not a problem for me, it seems crazy for a wiki to demand knowledge that I think is more complex than what it is trying to document.

I agree; if such a code example is going to be used, there should first be a simpler example that only requires basic knowledge and perhaps one or two other functions.

Finding good examples is an art form. ... Thus I have no problem presupposing some knowledge of maps in code examples.

I, for one, think that every function with a code-sample including maps should have a code sample without them first. Despite already being familiar with associate arrays from LISP, it still took me a bit of effort to wrap my head around exactly how to use maps in ash. I can understand that in many situations we may need to assume the user is familiar with their existence, but assuming the user is familiar with their syntax to demonstrate a rather simple function seems a bit much.

...but at its raw level function x()'s documentation should not be contingent on more knowledge of data structure y than is needed.

Exactly.

 

[CptJesus]

StDoodle, if you have a bit of time, would you join me on IRC? It looks like the channel is set up and running, and I wanted to get an idea of how exactly you're setting up the wiki right now.

 

[zarqon]

Happy to see where this is headed. You guys have your heads on straight.

I won't mind too terribly much adding in redirects to make searches for "function()" redirect to "function". Same problem, same solution, different direction.

EDIT: aqua -- I did actually mention (and somewhat organize) "the language itself" in my posted outline.

 

[StDoodle]

(Apologies for the double-post, if this even is at the rate this thread is going... things were just getting too long to edit in.)

[messes]

Yeah, we definitely want to take a look at standards for other things as well; functions just seemed like a good starting-point.

Sally's intro to scripting should probably go up (and her intro to Mafia, for that matter -- obviously both only if she's okay with it).

I don't know what the official policy is, but I'm of the opinion that anything posted on this forum should be fair game as a reference for the wiki. In my mind, posting a publicly-viewable guide should, in and of itself, be considered as permission to use the post as a guide. But a heads-up probably isn't a bad idea.

But I feel like I'm just sort of plopping information into whichever language page it might fit on (better than nothing, certainly).

That was what inspired this thread in the first place; I was originally just going to edit in some info on functions that didn't seem to have any information. It was when I realized that searching for a function without parentheses wouldn't give me any results (without jiggering with the options on the search results page) that I was "inspired" to tackle things at a deeper level, first.

I figured, if I was planning to update the wiki, noticed a couple of roadblocks and went "gee, where do I even begin..." then others have probably done the same. So I'd like to take care of that "beginning."

Which is to say, regimenting language features might be a lot harder, because there's probably no one template that can really handle them. But if anyone more wiki-aware than I has guidelines or suggestions for how pages like the typed constants page should be cleaned up, or how much other-programming-skill should be assumed when explaining ash programming language features, or anything like that... well, I'd be glad for some guidance.

Yeah, we need to make sure that we actually add some info to the "Help" pages that includes information on what templates we have, when they should be used, and what general guidelines to follow for anything that doesn't fit in with those templates. We should also point to such documentation on the "Talk" section of the Main Page.

As a programmer, the parens are part of the function name for me. They're the part that signals that this is the name of a function, not a variable, and when I'm just identifying a name as a function, the parameters aren't necessarily important. Thus I would talk about put_shop() to identify that I was talking about a function, and leave out the parameters because I don't like to type that much (also, since put_shop() is overloaded, leaving out the parameters lets me talk about any version of the function). From this point of view, the parens are part of the name and should be in the title. Redirects ahoy!

Again, the only arguments I make against including them stem from usability & maintainability of the wiki. If there's a way to change how Search works such that a search for "some_function" will automatically direct the user to the page titled "some_functionl()" then I have absolutely no problem with naming function pages that way. As it stands, doing so won't even show the "some_function()" page in the search results if the function name isn't repeated in the page text in certain ways, and there will be no indication that such a page even exists. This, in my mind, is too big of an issue to ignore.

 

[CptJesus]

Well, my 2 cents here. When I was writing my script, it was a total nightmare trying to search for functions I needed. I'm all for simplifying the search box to it actually work.

 

[bumcheekcity]

If the function names are done without parentheses and a user searches for the function name WITH parentheses, then they'll find it in the search. The other way round is not true.

 

[StDoodle]

I think (IMO) the all-around 'best' solution would involve (someone) writing a custom MediaWiki Extension that allowed for a page's titled to be appended when displayed. Then, the only time we wouldn't have the parentheses / might see an issue is when someone typed the url in manually. And if you're doing that, you better know what you're doing!

Really, I'm pushing we go the "no-parentheses" route for now, and find a way to alter titles later. The reverse is likely to be impossible because of the way MediaWiki (and most other wikis) works. If we added the extension "CustomTitle" it would be trivial to include, in the ash function page template, the addition of the parenthesis in how the title was displayed, without changing the requirements for linking to the title or altering how titles were searched for. Seems to me the best "middle ground."

Also, I'd like to add a request for another extension; SyntaxHylight. It does just what you might expect, in that it provides syntax highlighting for special <syntaxhighlight> tags (to be used in place of <code>). Seems like a natural for a wiki such as this.

 

[fronobulax]

As a programmer, the parens are part of the function name for me. They're the part that signals that this is the name of a function, not a variable

Interesting. I wonder if this is a generational thing, or at least a function of which languages were most influential in forming habits?

Probably because of a high experience and comfort level with strong typing, I tend to make very few presumptions about a name until I have a context for it. So, for example, when I first approach the documentation I want to know how do I find out the player's name? I don't care whether player_name is a global constant or a function, at this point. I just want to know that the information is available. Later, when I want to use the capability it does matter what it is but not initially.

I also tend to project my own presumptions of good design in places where that is not appropriate. Thus from a cognitive standpoint, I would avoid using (and thus having to document) global variables. If it never changes it can be a global constant. Otherwise I would expect it to be a function. So an API that I designed would be likely to present only functions to the user and thus the whole question - is it a variable or a function? - never comes up.

 

[fewyn]

Upgraded the wiki to 1.15.1 and installed ParserFunctions, SyntaxHighlight, and CustomTitle.

 

[StDoodle]

Upgraded the wiki to 1.15.1 and installed ParserFunctions, SyntaxHighlight, and CustomTitle.

Woo hoo! Thanks much, fewyn. Now to get down to serious work...

 

[fewyn]

Had to change the version on the parserfunction, works now for real.

 

[StDoodle]

For those who want to see what I'm currently planning, keep an eye on the page for "Test_again"; the page is internally named without (), but it shows up everywhere but the url with them. I'm hoping this is a good-enough best-of-both-worlds compromise for everyone; and bonus, it means you only need to type the function name once (well, without parenthesis) in the function page, and it shows up as it "should." (Proper case, parentheses, everything!)

Edit to add:

Did the SyntaxHighlight extension come with any documentation? I get the impression that there is a way to change the highlighting colors (css, something else, I dunno), but haven't had any luck finding that information.

 

[aqualectrix]

Hurrah, progress!

Just want to apologize a bit -- my long post on page 4 or so looks like it's ignoring several points made before it... because I hadn't read them yet. Oops. Sorry about that.

Which is to say:
- Zarqon's outline of wikiness looks very nice as a high-level thing
- StDoodle, as you're doing the work you should decide on paren-ness
- I love the parens solution you've come up with! It is fabulous!

 

[fewyn]

Yes StDoodle on the link I used above =p http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi

 

[StDoodle]

Yes StDoodle on the link I used above =p http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi

Oops, sorry, forget to mention that I meant "other than the built in defaults." Not a huge deal, I'm sure the community will decide on a default that's good enough (and far better than <code> for sure).

 

[heeheehee]

Since ASH obviously isn't one of GeSHI's supported language, we'll have to somehow come up with some file-thingy. I guess someone could modify that Notepad++ add-on thingy that Bale provided somewhere... But I have no idea what format this custom language file would require.

Also: Did anyone else notice that "ASH" happens to appear at the bottom of the page which fewyn linked to, in a manner completely unrelated to the ASH language with which we are all so familiar?

 

[fewyn]

This extension adds the <source> tag to present formatted source code, with support from Andre Simon's highlight program.

No.

 

[StDoodle]

Since, to the best of my knowledge, comments, basic data types, etc. are all c-like (which also means they're a-few-other-language-like), we should have a few options that fit for the most part.

Is it perfect? No. Is it better than what we had? By far, IMO.

As far as I'm concerned, if we get everything else really humming, and someone wants to take a look at prettier / more appropriate to ash options, great. Until then... it's better than yesterday.

And fwiw, SyntaxHighlighting wasn't a high-priority extension to me in the first place. However, the other two REALLY WERE, and I figured it'd be best to mention this one in time to have fewyn do them all at once, rather than ask for another change a week or so later.

Oh, and in case I haven't said it in the last couple of hours, thanks again fewyn for the changes; that really opens up a lot!

Also, I've moved all of my testing to my user page sandbox so as not to clutter the rest of the wiki (I'm hoping sandbox pages get flushed more often as well, 'cause I've got lots of edits & will have a lot more). So as to not overwhelm the recent change history & prevent "stomping on each others toes," I encourage other template-creators to follow my lead on this.

 

[StDoodle]

Ok, double-posting again, but I want to make sure this is noticed:

I can't for the life of me figure out any way to pass parameters to a template that will surround a parameters with the <syntaxhighlight> tags as needed. Unless someone comes up with some awesome mojo, I don't think we'll be able to dump absolutely everything into one master template for code pages.

This isn't a huge deal, in my opinion. As nice as it could be to have everything in one template, I think it has the huge downside of making it a bit more confusing than absolutely necessary. If anyone has a way around this, I'm open to hearing it. Otherwise, I'm going to go ahead on the assumption that we'll need a little bit of separation for our templates.

Also, if no solution to the above issue is found, I'm going to request fewyn make two modifications to how syntax highlighting is handled (by specifying a default language of "c" & making the modifications that enclose the code area in a dashed border as described on the extension's documentation).

While fulfillment of this request wouldn't hurt anything if done now, I'm holding off on making it an official request until this issue has had time to be reviewed by others (but if you read this, fewyn, and making those changes isn't a big deal, by all means go ahead; it's just that if we can use templates for code chunks, it isn't necessary; but I would be adding the same options into the template, so it wouldn't hurt).

Thanks all!

 

[heeheehee]

So I actually downloaded a copy of GeSHi, and it doesn't look -too- difficult to hack together something for ASH.

Attached is my attempt, made much easier by Bale's excellent Notepad++ language file. It'll have to be renamed as a .php, and then you should be able to upload it into extensions/SyntaxHighlight_GeSHi/geshi. Unless I totally suck at this sort of thing. Which is more than likely.