Ash documentation....

[Paragon]

Ok... I know that typing ashref in the gCLI will list some ash commands, and I know that there is a "manual" AND a wiki "Documentation" site... however even with all these resources it seems that there is quite a bit of "hidden" features in ash.
I would not mind helping to document the ash commands, but not all of them are shown when you type ashref. For instance, i know that notify is not listed and attack and a few of the consult script specific functions... Also it seems (I don't know for sure because i don't use the CLI too much) that a few of the CLI commands are not documented. Many of the functions documented are outdated, the names changed, the return values changed etc.

I think that the documentation wiki has a slightly clunky design. Would it be ok for me to try and do some updating? Where can I find a full list of ash functions (Is there somewhere in the source where it is all handled)? Where can I find a full list of CLI commands (again is there somewhere in the source where this is all listed)? Where can I find a full list of Consult script commands(somewhere in the source)?
My proposed plan of action:
Create a new wiki documentation from scratch on the current wiki documentation site.
Phase one: Create main_page_alpha
Phase two: Create wiki stubs for the complete design each stub ending with the _alpha postfix.
Phase three: Populate the stubs.
I think there should be a predefined template. Something along the lines of:
[feature name]
[cli name] [arg1][arg2]...[argN]
[argument1 meaning and valid values]
[argumentN meaning and valid values]
[A non technical overview of what this command does]
[return type] = [ash name] [argument1] [arg2]...[argN]
[ash name and arguments for overloaded]
[argument1 meaning and valid values]
[argN meaning and values]
[Non techincal overview of what this function returns]
Phase four: remove the _alpha postfix.
Phase five: Prepare for the future of kolmafia by keeping accurate documentation on the accuracy of each wiki page. To do this I propose there be some kind of accuracy ensured image label acc_[latest major kolMafia ver number.] Each wiki page would have a link to an image named acc_[major version kolMafia page is accurate for]. Whenever a major version is changed the image of acc_[major kolMafia ver number being replaced] is changed from whatever symbol means accurate to whatever symbol means outdated.
The main page would not contain this symbol, although next to each link to a functions information this symbol (or a smaller one) would indicate if the link had been updated for the newest ver.
Also I propose an Unupdated link which would contain a list of all the functions that have not yet been updated for the newest version to allow ease of updating. If a feature is completly removed or replaced the page for that feature would be considered updated when it is changed to reflect this removal or replacement.

I realize that this is quite a large task, I think I could get it going... However I don't have full knowledge on what each function actually does and what each arg is actually supposed to represent. Nor do I have full knowledge of what all the commands and functions actually are.

I think I may start this now... if anyone is opposed to this idea I would delete anything I had done before the idea was vetoed. This is simply a post to a) Request permission, b) Request support, and c) Create awarness of the propossed idea.

 

[Leperconartist]

Lol here's my support something like that could be extremely helpful to me as a n00b, although I don't even know of any functions I'm missing , I'd help but I can't because I don't know how. Anyway just wanted to give a thanks in advanced if your project gets going.

Leperconartist = Noob

 

[macman104]

I don't have the time to put in the resources to getting the whole thing started, but if you get things going and you just need people to fill in the information, I would be happy to do that. But if you want to provide the structure and just need people to fill in the info, I'd be more than happy. Just trying to get across that I don't really have time to offer to building pages and such, but I can certainly offer my time to put up text and such.

 

[Paragon]

I am a terrible wikist. My Wikis are ugly. However, if you want to see the general Idea of what I am talking about check out
http://wiki.kolmafia.us/index.php?title=Main_Page_alpha

It is still more of a sketch pad then the real deal.
I am open to suggestions on better formats or designs for the main pages, but i think the setup of the individual function pages are pretty good. Maybe some work could be done to make the template more contributer friendly. While it is true that some of the verbosity may be overkill for some of the simpler functions I think it is important to have a consistent format which can cover all the functions.
Also, the wiki doesn't seem to allow the uploading of images... if the KoLmafia devs decide to let this project proceed I would like to request that image uploads be enabled.

 

[efilnikufecin]

I would prefer to see something like thefollowing KOL wiki page.
http://kol.coldfront.net/thekolwiki/index.php/Category:Booze
to put a link to the Best drinks page http://kol.coldfront.net/thekolwiki/index.php/Best_Drinks into the list, they put the following code on the best drinks page:

[[category:Booze| Best Drinks]]

Using that method will later reduce page edits to http://wiki.kolmafia.us/index.php?title=Ash_commands_listed_alphabetically_alpha because we will be able to do what's needed from the new page we are creating.

Just something to consider.

see also: http://wiki.kolmafia.us/index.php?title=Category:Ash_Functions I might have been headed the same place as you with your page: http://wiki.kolmafia.us/index.php?title=Ash_commands_listed_alphabetically_alpha the reason not all Ash functions are listed is because pages have not yet been created for them. (note adding the function to the index is done from the functions own page)

I would love to see everyone on the same page working on the project, and I think we were pretty close.

I also while browsing noted http://wiki.kolmafia.us/index.php?title=Available_amount_alpha#RELAY_OVERRIDE lacked it's info. I forgot to log in, but filled it in. So far by my notes all functions except visit_url are the same in Relay over-ride scripts as they are in regular ash. The difference in visit_url being that if called with no arguments in a relay over-ride script the blanks are automatically filled in from the request which invoked the script.

 

[zarqon]

Awesome, I'd love to see (better) ASH documentation. Some things which are presently lacking from all current documentation:

- How to use the return value, i.e. what situations will result in what return value. Someone might want to know what index_of() returns if the substring is not found. Also, sometimes they are not intuitive return values -- for example, adventure() returns false if it stops due to completed conditions.

- Whether a function can result in an abort condition. For example, when retrieve_item() fails to get the item. This would be very handly for newbs, so they can learn to capture results if necessary.

I would be glad to help with this if we can all agree on a format.

 

[tebee]

Firstly can I say I wholeheartedly support the idea of having a complete and up to date wiki and am quite happy to do what I can to help.

Having had a play and added a few things I can see merits in both approaches being suggested. The list of commands shows which still need to be added as they're in red but the category approach has the advantage of being self maintaining.

As regards the detail level for the individual commands I quite live the template idea but there's a lot to fill in on it and I'm not sure how many people would know if command acted differently in a consult/Relay Override script - in fact just how many commands are there that do act differently?

I'm also not sure about how many commands are common to cli and ash, I know quite a few ash commands are just wrappers for their cli equivalents but in most cases the names are different, just a link would suffice.