mIRC Home    About    Download    Register    News    Help

Print Thread
Page 2 of 2 1 2
Re: Help File (Documentation) Improvements [Re: csylvain] #232216 24/05/11 05:43 AM
Joined: Apr 2010
Posts: 959
F
FroggieDaFrog Offline
Hoopy frood
Offline
Hoopy frood
F
Joined: Apr 2010
Posts: 959
I've been scripting for 10+ years. When I started, I read the entirety of each text file, and help file before I even began. The help file is quite clear if the user actually reads it in the order it was meant to be read instead of skimming through it trying to figure out how to put pieces together.

Yes I do agree, the help file can, at times, be misleading but it's a help file for mIRC and it's features, not an "everything about everything for mIRC" file. Sometimes less is more when it comes to explaining things, especially to new users. mSL scripting is opened source and has a huge community on and off IRC, so if there's questions IMHO it'd be easier to find one of those outlets than to refer to a help file that can not be interacted with.

As for what should and shouldn't be documented; somethings are just too complicated to be explain in the help file(IE: Regular expressions), others are just too out of date to maintain documentation on when there is/are far superior methods($ifmatch vs. $v1/$v2)

I understand some things aren't as clear as they should be but you have to draw the line somewhere. I'd hate to be looking for, as an example, how to read a text file, and have to read through 9 pages of information to find what I needed.

mIRC's help file is short and to the point. It tells what a command can do, what an identifer returns, etc without overwhelming the user with information that isn't important or directly related to the topic. Yes it might take some fiddling to find what you need due to this but I'd rather it be a little unclear then have 9pages of information to go through.


I am SReject
My Stuff
Re: Help File (Documentation) Improvements [Re: csylvain] #232217 24/05/11 06:25 AM
Joined: Jul 2007
Posts: 1,129
T
Tomao Offline
Hoopy frood
Offline
Hoopy frood
T
Joined: Jul 2007
Posts: 1,129
Think of mIRC's help file as a basic booklet, which you can quickly reference any info you want to review. By relaying on it is never enough. What one should do is practice, ask questions, and learn from the experienced to gain better improvement. You'll eventually realize that you're getting better at MSL with a sense of achievement. It's a surprising process that will grow with you over the long haul. Just keep at it.

Re: Help File (Documentation) Improvements [Re: csylvain] #232218 24/05/11 07:12 AM
Joined: Sep 2005
Posts: 2,881
H
hixxy Offline
Hoopy frood
Offline
Hoopy frood
H
Joined: Sep 2005
Posts: 2,881
I didn't intend my post to come across as arrogant, so I'm sorry you interpreted it that way.

Once you read the help file for /help on QUIT there are a few hints that $chan won't exist:

1) The event description - "The on QUIT event triggers when a user quits IRC while on the same channel as you."
2) The event format - "on level:QUIT:" - there is no target parameter here like there is for on join/part/action/notice/etc
3) The script example - it doesn't use $chan but instead uses /ame, which if you look up in the help file sends an action message to all channels.

The reason I suggested that it was spoon feeding scripters to provide the $comchan example is because the quit event is channel-less. It is therefore not necessary for Khaled to explain how to get the channels you share with that particular nickname. It is a special type of script that would require the channels, such as a theme. It's not the developer's job to give specialised examples.

I'm not sure exactly what you expect the help file to be, but what steps did you take to try to find $chan(N) ? I've been a member of this forum since around 2003/04 (went by different usernames back then) and I can say that $chan(N) has been used hundreds of times on this board. It's not some hidden and ultra-complicated identifier that is rarely used :P

My point is that the documentation already contains the information you need, you're just not looking for it. To get more elaborate examples you really need to join a scripting forum such as this one, or go and lurk in a help channel to see questions asked and answered.

You can also search on websites like mircscripts.org to see if a particular script you're trying to do has already been done and, if so, look at how it was written.

I'm not saying the help file can't use improvements, it's just that I don't know a language on the planet where you only need the help file to learn it properly. Examples and discussions with other like minded coders always helps.

Re: Help File (Documentation) Improvements [Re: csylvain] #232222 24/05/11 02:27 PM
Joined: Oct 2004
Posts: 8,330
Riamus2 Offline
Hoopy frood
Offline
Hoopy frood
Joined: Oct 2004
Posts: 8,330
mIRC's help file is actually one of the best help files you will find that comes packaged with a program used to script/program something. Probably not the best, but it's right up there at the top. Most programming software will give you a small number of examples and very short description or simply the syntax of individual commands. They usually don't provide a list of what works and doesn't work or how to do specific things. mIRC's help file often has examples and usually has pretty decent descriptions rather than just syntax. Most other programming software expects you to learn to program somewhere else and the help file is just a minor reference that really isn't all that helpful except for checking syntax. mIRC provides you with enough in the help file to write many commonly used scripts without ever resorting to any other information (at least, if you know anything about programming/scripting beforehand). And for what it doesn't provide, then you are expected to look elsewhere, just like any other language. A help file that is a few thousand pages because of being filled with information that isn't really necessary becomes useless.

If anyone remembers the old DOS manuals, they were very thick manuals that were filled with a lot of useless information that made finding useful information difficult. Since then, manuals and help files have been significantly trimmed down and cleaned up so they are useful. Yes, it means there may be something missing that you wish was there, but it means that everything else is easy to find. And it's easy enough to find information that isn't included in the help file.

This forum is a very good resource for any questions. You may have trouble finding something specific using Search depending on how you try to search for it, but if you ask a question, you will get an answer. It may require waiting a little for the answer, but you'll get it. If you're in a hurry, there are a variety of scripting channels where you can quickly receive help.

When I started scripting in mIRC, I had already had many years of programming experience, so I did know enough to understand much the language before I even started. It was mostly just syntax that I needed to learn and any of the more advanced or specific things in mIRC. I learned by taking a script (a trivia bot script [I think TrivBot]) and trying to improve on it. I mostly used the help file and when I needed more information, I used #scripting on Dalnet. That's all I needed to improve that script and learn how to script in mSL. After I learned the basics that way, I moved on to using a combination of the help file and this forum. Mostly I just use the help file. It's rare if I need to ask in the forum. It also helps that I read all posts on this forum by checking the site daily. Doing so lets me learn from other people's scripts and also try to solve scripting problems for people. That alone has been a great help in learning the language and especially the more advanced things you can do.

What it comes down to is that you need to use other sources as well as the help file. The help file is not the only source for information and it's not meant to be the only source. It's meant as *one* resource only. A very useful one, but still only one of many. As I mentioned before and others have also said, *yes*, the help file can be improved in certain ways. But it doesn't need to provide a list of identifiers that are $null for every event or to tell you if an event is used for a channel or a network or something else.

As mentioned, the events are clear in what they relate to. If it has a channel (location) field, then it is for use in a channel (or PM or whatever). If it does not, then it isn't. on QUIT does not have a location field, so that should give you a good indication that it is not related to the channel at all and so $chan would be $null. The same goes for on EXIT, on CONNECT, on DISCONNECT, on LOAD, on START, etc. None of those have a location field, so $chan will always be $null in those events and any similar events. Perhaps that isn't spelled out for people in large bold text in every event, but it can easily be inferred from looking at the various events and examples in the help file.


Invision Support
#Invision on irc.irchighway.net
Re: Help File (Documentation) Improvements [Re: csylvain] #232251 26/05/11 06:46 PM
Joined: Dec 2002
Posts: 1,527
L
landonsandor Offline
Hoopy frood
Offline
Hoopy frood
L
Joined: Dec 2002
Posts: 1,527
Im gonna make an overall reply here with no assaults to anybody - just my own $.02 USD.

The mirc help file is really good. I've used it tons of times and it's helped me out. I DONT have a long programming background, I've played with programming in general since the time of the commadore/apple basic programming language, i've done some basic HTML as well. I think the BIG problem with the mirc help file is that it's written in one way, and many who DONT have a large background in programming MAY have difficulty with it. I used to teach the basics of scripting (the style that worked for me) to other and they were successful with it, but I reached a plateau. I wanted to go further, but ran out of an effective teacher. These forums are AWESOME and always have been, but you can't replace one on one training with somebody who understands how you think. The help file should NEVER try to do this. It CANT be everything to everyone. If anything, I think it needs to be said that not everybody can program (script in this case) and not everybody will understand the scripting language. In the past I even made comments about combining the mirc help file with the irc intro guide. I felt (at the time) that there needed to be more of a marriage between the two documents because it seemed to me that the IRC intro had better examples than the basic MIRC help file. Perhaps what's REALLY needed is a help file, from a scripter, who's been doing it for a while, that can break down the language into easier digestible bytes (ha ha ha). Will I be the one to do it? Nope, cause 1) I barely use mirc anymore 2) at my best I was WAAAAAAAAY outmatched in my scripting knowledge. Am I asking one of the pros here to do it? Nope, unless they WANT to. I also know there's websites out there that do try to teach people who things work and they do a good job of it. me personally, I need that interaction with a person to work out my issues, but I've gotten info from scripts and websites and tweaked em for my purposes and have learned a great deal from those.

Over the years scripting seems to have gotten a bad rap. People with the knowledge get labelled as elitists or other titles. I myself never found that to be the case. SOME people are bad teachers, some are hard to approach, but I'm sure help can be found if you look for it. There are channels that give help on scripting on the networks you're already on most networks I would imagine. keep in mind that they get bombarded with questions from easy to difficult by all walks of life and they made have their own policies on what they will and wont help with.

All in all, the documentation provided is really good, the message board here is awesome as well, but you can't expect people to do your work for you. I've seen MANY posts in my, what..... almost 10 years on the various mirc message boards..... where the people trying to help give very in depth explanations and some where it's just a snippet with "try this type of code". When in doubt, ask, if not sure, ask again, if you dont get a response that you understand, ask some more but give the part that you have problems with.


Those who fail history are doomed to repeat it
Re: Help File (Documentation) Improvements [Re: landonsandor] #232253 26/05/11 08:13 PM
Joined: Oct 2004
Posts: 8,330
Riamus2 Offline
Hoopy frood
Offline
Hoopy frood
Joined: Oct 2004
Posts: 8,330
Just had to say that that's a great post. You have summed it up perfectly.


Invision Support
#Invision on irc.irchighway.net
Re: Help File (Documentation) Improvements [Re: Riamus2] #232264 28/05/11 12:46 AM
Joined: Dec 2002
Posts: 1,527
L
landonsandor Offline
Hoopy frood
Offline
Hoopy frood
L
Joined: Dec 2002
Posts: 1,527
Thanks Riamus smile


Those who fail history are doomed to repeat it
Re: Help File (Documentation) Improvements [Re: csylvain] #232270 28/05/11 02:52 PM
Joined: Jan 2007
Posts: 1,156
D
DJ_Sol Offline
Hoopy frood
Offline
Hoopy frood
D
Joined: Jan 2007
Posts: 1,156
Bottom line is get some experience with mIRC, then the help file will make more and more sense. Even if you have experience with other languages and tech manuals, you still need to understand the IRC protocol to understand the mIRC help file to the depth you are requesting.

Maybe you should start by reading about the IRC protocol. I never did, I just got it from experience. When all fails, /echo is your friend. You can use it to tell you exactly what an identifier returns in an event.

As a general rule, if #channel is not in the event you won't be able to use # or $chan to return a channel name.

on *:join:#:{ <== Channel is in event.

on *:quit:{ <== Channel is NOT in the event.

Re: Help File (Documentation) Improvements [Re: DJ_Sol] #232399 02/06/11 11:54 PM
Joined: Dec 2002
Posts: 1,527
L
landonsandor Offline
Hoopy frood
Offline
Hoopy frood
L
Joined: Dec 2002
Posts: 1,527
See, but the problem is, in many cases, people CANT get experience (unless things are explained to them) so they'll NEVER understand it. I agree they need to get experience, but what if they wanna script and can't get the experience? Then what do they do? I know, it's easy to find some simple scripts to get used to, but think about what you're suggesting - it's a catch 22 in many cases. I dont think you're wrong, but I dont think you're fully right either


Those who fail history are doomed to repeat it
Re: Help File (Documentation) Improvements [Re: landonsandor] #232403 03/06/11 01:10 AM
Joined: Oct 2004
Posts: 8,330
Riamus2 Offline
Hoopy frood
Offline
Hoopy frood
Joined: Oct 2004
Posts: 8,330
In most cases, anyone scripting in MSL has learned mostly on their own without anyone teaching them. Why? Because you can't just take a MSL course in college and I haven't seen any MSL for Dummies books anywhere (yet). What this tells me is that it is very possible to learn without someone teaching it to you. Yes, it's true that you will learn more easily if you've done some kind of programming or scripting before, but that's true no matter what. If you've never programmed/scripted before, then it will just take more effort and time to learn, but you can still learn.

The point most here are trying to make is that the help file is a resource that is useful but not meant to be the only resource. There are many other resources that can be used and do not require any special skill to make use of, such as this forum or other scripting forums, scripting channels on IRC, other scripts, etc. Expecting a single source to teach you everything and answer all of your questions is crazy.

And there really isn't a Catch 22. You do not need experience to begin learning from any of these sources. You may need to make use of more than one source to learn something, but the point is that you *can* learn regardless of experience. As you start learning, your experience increases and you will be able to learn more difficult things. Think about it... just about every programming language's beginning instruction book gives you a Hello World example and has you start there. By itself, it's a very useless thing, but it fulfills a purpose... it starts giving you experience by teaching you some of the most basic commands in the language that you will then be able to use to build up to the next commands and so on. As long as you are willing to start small and work up, building a strong foundation on the way, you will be able to learn on your own with the resources available even if you have no experience whatsoever.


Invision Support
#Invision on irc.irchighway.net
Re: Help File (Documentation) Improvements [Re: Riamus2] #232419 03/06/11 05:04 PM
Joined: Sep 2005
Posts: 2,881
H
hixxy Offline
Hoopy frood
Offline
Hoopy frood
H
Joined: Sep 2005
Posts: 2,881
Originally Posted By: Riamus2
In most cases, anyone scripting in MSL has learned mostly on their own without anyone teaching them. Why? Because you can't just take a MSL course in college and I haven't seen any MSL for Dummies books anywhere (yet). What this tells me is that it is very possible to learn without someone teaching it to you. Yes, it's true that you will learn more easily if you've done some kind of programming or scripting before, but that's true no matter what. If you've never programmed/scripted before, then it will just take more effort and time to learn, but you can still learn.

The point most here are trying to make is that the help file is a resource that is useful but not meant to be the only resource. There are many other resources that can be used and do not require any special skill to make use of, such as this forum or other scripting forums, scripting channels on IRC, other scripts, etc. Expecting a single source to teach you everything and answer all of your questions is crazy.

And there really isn't a Catch 22. You do not need experience to begin learning from any of these sources. You may need to make use of more than one source to learn something, but the point is that you *can* learn regardless of experience. As you start learning, your experience increases and you will be able to learn more difficult things. Think about it... just about every programming language's beginning instruction book gives you a Hello World example and has you start there. By itself, it's a very useless thing, but it fulfills a purpose... it starts giving you experience by teaching you some of the most basic commands in the language that you will then be able to use to build up to the next commands and so on. As long as you are willing to start small and work up, building a strong foundation on the way, you will be able to learn on your own with the resources available even if you have no experience whatsoever.


I got schooled by this community mostly laugh

When you're new to programming/scripting, joining an enthusiast website and asking stupid questions is the best way to learn.

Page 2 of 2 1 2