Introduction post
Holatuwol challenged us to pick up the gauntlet of ASH training, and I think that he is right to have done so. Not simply because we are all a bunch of overdependent do-nothings, but also because the developers have been too busy with new and fabulous features to keep the manuals in proper reflection of the state of the product. In short, we're the right people to document ASH and this is the right place to document ASH, so let's get to it! So here's my little introductory FAQ:
What can I learn here? What can't I learn here?
It is my intention that this manual cover the functions in ASH. That is, the words that are followed by a set of parentheses that maybe have things inside them. I'm not going to cover the fundimentals of the ASH language specifically or structured programming in general. I hope someone else feels compelled to write something up to cover that, because it is a great subject and I think that ASH would be an ideal first programming language for someone to learn. I'm also not going to cover other script-ish parts of KoLmafia like CLI, CCS, or moods -- again, someone else is welcome to step up to the plate.
How is this manual going to be different from the old one?
Content-wise, not very different at all. I've got some different notions on how to group the functionality together to cover common themes so that the function you're looking for might be easier to find.
The major difference that I think will be useful is that this manual will provide a link from the functions to actual working scripts in this repository that use the functions in context. So there won't be any question about how or why one would want something, it's just right there. This will also provide, I hope, a survey of proper syntax and best programming practices while also showcasing the diversity of writing styles among sound programmers.
How complete is the manual?
Umm, I'm not certain. I had the functions from the old manual stored on my hard drive, and I've added in the functions that Holatuwol added for us over the past few weeks, and I've scratched my head a few times saying things like "Hey, why isn't sell_item() here?" If you see stuff missing, call me on it. Eventually, I'll sit down with a bottle of wine and the ASH source code and make sure that it's all included.
Hey wait, I want to suck up to Holatuwol too!
Outstanding, there's lots left to do! Like I mentioned before, there is the fundimental language reference to write for people who don't know about "if" and "return" and global variables and maps and the ASH raw data types. Also, someone who is more in-depth with CLI can try to recreate that manual or offer to revise it and get the old copy.
In addition, I'd love to have people volunteer their scripts as examples. I want to be a little particualr here, because I don't want every script ever written to overshadow the goals of the document. At the moment, I'm looking for something that is well-written and commented, that uses functions that do not currently have examples given, and is not unreasonably long. I may turn out to be pickier than that by the time all is said and done, so forgive me in advance if you offer something and I turn you down.![Smile :) :)](data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7)
(Mods, I know that I'm about to double post. I hope you can appreciate the benefits of keeping these two posts separate. Cut my post count in half if you think I'm deliberately spamming to make myself seem important. :
)
( this is why I call them "guidelines" rather than "rules". Carry on, soldier! ;-) -Daychilde )
ETA: Did I say double-post? I evidently meant multi-post, due to the size restrictions on the posts. But that's the last of it, with enough room for editing in the future I think!
Holatuwol challenged us to pick up the gauntlet of ASH training, and I think that he is right to have done so. Not simply because we are all a bunch of overdependent do-nothings, but also because the developers have been too busy with new and fabulous features to keep the manuals in proper reflection of the state of the product. In short, we're the right people to document ASH and this is the right place to document ASH, so let's get to it! So here's my little introductory FAQ:
What can I learn here? What can't I learn here?
It is my intention that this manual cover the functions in ASH. That is, the words that are followed by a set of parentheses that maybe have things inside them. I'm not going to cover the fundimentals of the ASH language specifically or structured programming in general. I hope someone else feels compelled to write something up to cover that, because it is a great subject and I think that ASH would be an ideal first programming language for someone to learn. I'm also not going to cover other script-ish parts of KoLmafia like CLI, CCS, or moods -- again, someone else is welcome to step up to the plate.
How is this manual going to be different from the old one?
Content-wise, not very different at all. I've got some different notions on how to group the functionality together to cover common themes so that the function you're looking for might be easier to find.
The major difference that I think will be useful is that this manual will provide a link from the functions to actual working scripts in this repository that use the functions in context. So there won't be any question about how or why one would want something, it's just right there. This will also provide, I hope, a survey of proper syntax and best programming practices while also showcasing the diversity of writing styles among sound programmers.
How complete is the manual?
Umm, I'm not certain. I had the functions from the old manual stored on my hard drive, and I've added in the functions that Holatuwol added for us over the past few weeks, and I've scratched my head a few times saying things like "Hey, why isn't sell_item() here?" If you see stuff missing, call me on it. Eventually, I'll sit down with a bottle of wine and the ASH source code and make sure that it's all included.
Hey wait, I want to suck up to Holatuwol too!
Outstanding, there's lots left to do! Like I mentioned before, there is the fundimental language reference to write for people who don't know about "if" and "return" and global variables and maps and the ASH raw data types. Also, someone who is more in-depth with CLI can try to recreate that manual or offer to revise it and get the old copy.
In addition, I'd love to have people volunteer their scripts as examples. I want to be a little particualr here, because I don't want every script ever written to overshadow the goals of the document. At the moment, I'm looking for something that is well-written and commented, that uses functions that do not currently have examples given, and is not unreasonably long. I may turn out to be pickier than that by the time all is said and done, so forgive me in advance if you offer something and I turn you down.
(Mods, I know that I'm about to double post. I hope you can appreciate the benefits of keeping these two posts separate. Cut my post count in half if you think I'm deliberately spamming to make myself seem important. :
( this is why I call them "guidelines" rather than "rules". Carry on, soldier! ;-) -Daychilde )
ETA: Did I say double-post? I evidently meant multi-post, due to the size restrictions on the posts. But that's the last of it, with enough room for editing in the future I think!