Forums Feature Suggestions Help File (Documentation) Improvements

the documentation for "on QUIT" needs some additional words to the effect:
$chan is $null when processing this event, although the applicable nickname is supplied by $nick. More than one channel may be affected by the client quit from a server. The number of affected channels is $comchan($nick,0). The channel names are $comchan($nick,N).

similarly, the documentation for "on DISCONNECT" needs a few more words:
$chan is $null when processing this event. More than one channel may be affected by a server disconnect. The number of affected channels is $comchan($me,0). The channel names are $comchan($me,N).

p.s.: what's this I see about an "undocumented ME level" in event processing? How about at least a documentary mention in the ChangeLog?

on Me:userlevel:Event.....:{
stuff
}

<grumpy>
ok, that's syntax. great. Semantics please!
IOW - that's _how_ you do it but what is the purpose?
</grumpy>

on me:*:EVENT:{} only triggers if $nick == $me

thanks!

From: versions.txt

25/11/95 - mIRC v3.8

Changes:
..
23.Added "me" prefix to remote definitions, eg.:
me:1:ON JOIN:/msg etc...
This limits a command definition to reacting only to
events caused by your client. This is useful in case you
use Bots which have the same address as you.

-

07/09/96 - mIRC v4.6

Changes:
..
50.Fixed "me:" prefix for remote definitions.

i think "only triggers if $nick == $me" is better.

While the help file may be improved in numberous ways (and I keep hoping for a general overhaul), I'd like to object to the whole "channels affected" thing. A disconnect always affects the whole network connection, it simply is not related to any particular channel, even though you may link it to channels with a script. Likewise a user does not quit one or more particular channels - if he quits, he leaves the whole network.
There are numberous other events not related to a specific channel by the same token, yet scripts may require to link them - are all of them in need of the same "improvement"? Some other time, you might want to relate this or that event to a different identifier - itemizing each and every possibility does not look like the right route to me, especially as you could tie virtually every identifier to virtually every event.

Yeah these events deal with that single connection to the server. Not the channels. $server or $network should return where the connection is connected to. There are many tools to access data from a single connection like scid, or scon.

If you want to know what channels you had open on a single connection that disconnected, $chan(0) returns total channels like normal. And therefore, $chan(1), $chan(2), etc. will return the individual channel names. I prefer these over $comchan.

$chan has no place in disconnect or quit so of course $chan would be $null.

Documentation of "hidden" features can be found in the version.txt file thought its a very long and boring read.

ok! even better. $chan is $null because it has no place in "on QUIT" or "on DISCONNECT" or whatever words it takes since the documentation may mislead one to believe $chan is always defined to something other than $null. Instead use $chan(N).

My research into why $chan was $null (the reason for it was not clear), I only found $comchan mentioned here in a Forum post.

as for the long boring read, the quoted text doesn't exactly throw light onto the "me" level sufficient for clarity. yes, it's a deep detail but it shouldn't be murky!

I don't think it's murky at all. The ME prefix limits events to being triggered only by your client (yourself).

This...


is the same as this...

you are quite clear but the text "This limits a command definition to reacting only to events caused by your client. This is useful in case you use Bots which have the same address as you." (quoted from the changelog) doesn't seem as clear.

The changelog isn't really meant as a help file, but just a list of changed/fixed/new items and sometimes a short description. So it doesn't really need to be any more clear. The help file could definitely use some improvements in certain areas, and you can find various posts recommending improvements. In general, it is a very useful file and is quite useable as-is, so it's most likely low on the priority list of things to work on. There are a variety of undocumented commands/etc, but there are also various online resources that list these commands and what they do, so if you wanted to look at the commands, it's easy enough to do so. The one problem with using undocumented commands is that they may be removed at any time, where documented commands aren't going anywhere.

The help file and version.txt make a lot more sense the longer you work with mIRC. It took me about 2 years before I could refer to the help manual and understand what it was telling me. Up until then I had friends and old code ideas to help me.

Keep it up!

i've been working with man pages and software documentation for quite a long time. you're right that multiple passes through documentation are necessary.
however, when documentation gives little indication when variables are defined or are $null depending on which Event is being processed, then the documentation seems lacking some useful information. in my effort to assist improving a product I have spent money on, I offer the suggestion to note what is missing from the "on QUIT" and "on DISCONNECT" sections of the help file and request the adding of a mention of the usefulness of $chan(N) when processing those events.
in addition, I note in the "Remote" section of the help file, where it appears is a list of each event and links to 'examples and tips on how to use them', the event "DISCONNECT" is not present. If a link is added in that part of the help file, it would need only lead to the same place as the "CONNECT" link since at present they are documented together on one page.
as for this "me" level, it would seem the consensus is it is not a very useful feature (checking "if $nick == $me" is a substitute and is also more descriptive script-wise). Documenting it as "deprecated and marked for removal as of version X" may be in order?

There are MANY things that are $null in basically every event. Should the help file list every $null item for every event or command? No. That would just be unnecessary (and basically useless) filler. It doesn't take much effort to learn what can and cannot be used in an event.

As far as the ME item, it is not deprecated and it is not marked for removal, so I don't see any reason why you would put such a note in there. The point I made before was that undocumented features MAY be removed, not that they are GOING to be removed. And ME is useful. It prevents the event from even firing it you aren't the one who triggered it, whereas the IF check only happens after the event fires. That may not be a big deal most of the time, but it allows you to have 2 separate "identical" events in the same script file if you want to. For example:



Yes, you can put those into one and use an IF/ELSE, but some people may prefer to keep things separate. As with many features, there may be multiple ways to do the same thing and neither way is right or wrong... it's just a preference which way you choose.

Anyhow, yes, the help file can be improved and pretty much anyone here would agree. But saying something is deprecated isn't necessary... if it's deprecated, then it's removed at the same time. And mentioning everything that is $null for every command/event/etc is just a waste of space. If you aren't sure if something is $null, use echo to find out.

I'm thinking ON TEXT was a bad example for this since you can't trigger it anyway.

Lol. Oops. Ok, well... it's a bad example, but it at least demonstrates something you could do. Change it to any event that works for both others and you.

The documentation can't really be expected to list every identifier that is $null for every event. That would take years and the benefit of having such information wouldn't really be worth the effort. Unless you're suggestion he only do it for some events and not others, but that would only lead to inconsistencies in the documentation.

What usually happens is that someone will try to use $chan in on QUIT/on NICK (the two most common events where people expect this identifier to work), and when it doesn't, they will either ask a friend, help channel or online forum why it's not working. Once the reason has been explained it's pretty obvious why this identifier doesn't work for those events; they are not channel-specific events, they are network specific.

You cannot use $chan(N) as an identifier to use in those events to get the shared channels between you and that nickname because $chan(N) already does something different. $comchan($nick,N) works perfectly fine. Why re-invent the wheel and break an existing identifier at the same time?



Whilst Khaled could add a section to the help file that mentions this, it's not really his job to spoon feed scripters. $comchan() is documented in the help file and on QUIT/on NICK are network-specific events, not channel-specific. You can put 2 and 2 together to figure out what you need to do to get the channels shared between you and the nick triggering the event.



on DISCONNECT should maybe have an example, but I expect the reason it doesn't is because the syntax is exactly the same as on CONNECT. The only difference is it triggers when you disconnect rather than when you connect!



It's useful in the sense that it's quite a bit shorter than the alternative, making it easier and faster to type if you just need to write up a quick script.

Khaled doesn't usually remove features. There are deprecated features that have been there for years and years.

For example:



/setlayer is deprecated but you can still use it to set transparency of desktop windows.

Documenting a deprecated feature seems a little silly to me.

who said anything about spoonfeeding scripters? that's a very arrogant position to take on the matter at hand and rude as well.

what seems missing then in the documentation is the distinction between channel-specific and network-specific events. if by documenting this distinction it becomes clear certain event variables will or won't be defined, then you have accomplished something. Just the fact that some will or won't be defined is a hint for goodness sake! So you're an expert on the entire IRC RFC series - nice, how nice for you. But to expect every scripter at least attempting to do something useful with a script to be expert on the entire body of knowledge first is the essence of the worst kind of arrogance.

For what I have accomplished - a window of active nicks per channel that indicates how soon it has been since the last activity was noted and removes inactive nicks - $chan(N) does the job needed. $comchan($me,N) does the same, however it took quite a bit of effort and research to encounter the one (or was it only two) places in the Forum where this information could be found. $chan(N) itself never appeared in those Forum posts.

There a classes of events. There are certain things which apply and will be defined and certain things which do not apply and won't be defined. Great! Document the hell out of that, will ya?!

Who said "on DISCONNECT" needs an example? I said there's a list which gives the impression of being The Canonical List of Events which is missing an entry for DISCONNECT which is an event that can be processed. An oversight? perhaps. should the oversight or lack of entry be defended as being How It Ought to Be? doubtful. If I could add the entry myself, much as one adds to a Wiki, I would have done so already. But I cannot. I must instead use this Forum to make the case and maybe Something Will Be Done. Good move on not saying "thanks" for my good intent.

You have a closed-source scripting language here, so how the heck does one find the definitional information about the language if not in the Documentation. Oh, sure, try the Forum. Maybe it'll help - maybe it won't. I don't happen to subscribe to that notion. Rather, I subscribe to the "you the author and supporters know you can do better documentation, so do it, why don't you please?" notion.

yes, granted, I am writing this while under the full influence of testiness caused by your taking a greater than thou stance on the matter at hand. if you don't see what you did there... well... just know i've written many things in many languages and never before have I encountered this level of "surprise" when developing new code. if you choose not to respect that, it's your own fault.

as for documenting a deprecated feature: that's called "hey if you've written a script using this here feature be well and truly informed it is slated to go away. Adjust your scripts accordingly." The feature has been (perhaps cavalierly) documented informally. Alternatively, since the feature appears to have supporters, document it since it's useful and is not deprecated! You're stuck with the fact it is in fact documented at present in a feeble way. Fix -that-, why don't you?

The effort expended on this thread could have already made significant improvements to the Help File part of the product.