mIRC Home    About    Download    Register    News    Help

Print Thread
Page 1 of 2 1 2
Help File (Documentation) Improvements #232109 19/05/11 09:05 PM
Joined: Jan 2011
Posts: 14
C
csylvain Offline OP
Pikka bird
OP Offline
Pikka bird
C
Joined: Jan 2011
Posts: 14
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?

Re: Help File (Documentation) Improvements [Re: csylvain] #232110 19/05/11 09:41 PM
Joined: Apr 2010
Posts: 921
F
FroggieDaFrog Offline
Hoopy frood
Offline
Hoopy frood
F
Joined: Apr 2010
Posts: 921
on Me:userlevel:Event.....:{
stuff
}


I am SReject
My Stuff
Re: Help File (Documentation) Improvements [Re: FroggieDaFrog] #232111 19/05/11 10:00 PM
Joined: Jan 2011
Posts: 14
C
csylvain Offline OP
Pikka bird
OP Offline
Pikka bird
C
Joined: Jan 2011
Posts: 14
<grumpy>
ok, that's syntax. great. Semantics please!
IOW - that's _how_ you do it but what is the purpose?
</grumpy>

Re: Help File (Documentation) Improvements [Re: csylvain] #232113 19/05/11 10:12 PM
Joined: Dec 2002
Posts: 339
D
drum Offline
Fjord artisan
Offline
Fjord artisan
D
Joined: Dec 2002
Posts: 339
Originally Posted By: csylvain
<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

Re: Help File (Documentation) Improvements [Re: drum] #232114 19/05/11 10:17 PM
Joined: Jan 2011
Posts: 14
C
csylvain Offline OP
Pikka bird
OP Offline
Pikka bird
C
Joined: Jan 2011
Posts: 14
thanks!

Re: Help File (Documentation) Improvements [Re: csylvain] #232115 19/05/11 10:27 PM
Joined: Dec 2002
Posts: 2,010
R
RoCk Offline
Hoopy frood
Offline
Hoopy frood
R
Joined: Dec 2002
Posts: 2,010
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.

Re: Help File (Documentation) Improvements [Re: RoCk] #232116 19/05/11 10:46 PM
Joined: Jan 2011
Posts: 14
C
csylvain Offline OP
Pikka bird
OP Offline
Pikka bird
C
Joined: Jan 2011
Posts: 14
i think "only triggers if $nick == $me" is better.

Re: Help File (Documentation) Improvements [Re: csylvain] #232117 20/05/11 12:15 AM
Joined: Nov 2006
Posts: 1,559
H
Horstl Offline
Hoopy frood
Offline
Hoopy frood
H
Joined: Nov 2006
Posts: 1,559
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.

Re: Help File (Documentation) Improvements [Re: csylvain] #232118 20/05/11 01:03 AM
Joined: Jan 2007
Posts: 1,156
D
DJ_Sol Offline
Hoopy frood
Offline
Hoopy frood
D
Joined: Jan 2007
Posts: 1,156
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.

Re: Help File (Documentation) Improvements [Re: DJ_Sol] #232119 20/05/11 01:29 AM
Joined: Jan 2011
Posts: 14
C
csylvain Offline OP
Pikka bird
OP Offline
Pikka bird
C
Joined: Jan 2011
Posts: 14
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!

Re: Help File (Documentation) Improvements [Re: csylvain] #232120 20/05/11 04:17 AM
Joined: Dec 2002
Posts: 2,010
R
RoCk Offline
Hoopy frood
Offline
Hoopy frood
R
Joined: Dec 2002
Posts: 2,010
I don't think it's murky at all. The ME prefix limits events to being triggered only by your client (yourself).

This...
Code:
on ME:*:JOIN:#: {
  msg # Hello $+(#,!) How are you today?
}


is the same as this...
Code:
on *:JOIN:#: {
  if ($nick == $me) {
    msg # Hello $+(#,!) How are you today?
  }
}

Re: Help File (Documentation) Improvements [Re: RoCk] #232125 20/05/11 11:49 AM
Joined: Jan 2011
Posts: 14
C
csylvain Offline OP
Pikka bird
OP Offline
Pikka bird
C
Joined: Jan 2011
Posts: 14
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.

Re: Help File (Documentation) Improvements [Re: csylvain] #232130 20/05/11 02:59 PM
Joined: Oct 2004
Posts: 8,327
Riamus2 Offline
Hoopy frood
Offline
Hoopy frood
Joined: Oct 2004
Posts: 8,327
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.


Invision Support
#Invision on irc.irchighway.net
Re: Help File (Documentation) Improvements [Re: csylvain] #232132 20/05/11 03:01 PM
Joined: Jan 2007
Posts: 1,156
D
DJ_Sol Offline
Hoopy frood
Offline
Hoopy frood
D
Joined: Jan 2007
Posts: 1,156
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!

Re: Help File (Documentation) Improvements [Re: DJ_Sol] #232135 20/05/11 06:38 PM
Joined: Jan 2011
Posts: 14
C
csylvain Offline OP
Pikka bird
OP Offline
Pikka bird
C
Joined: Jan 2011
Posts: 14
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?

Re: Help File (Documentation) Improvements [Re: csylvain] #232136 20/05/11 07:21 PM
Joined: Oct 2004
Posts: 8,327
Riamus2 Offline
Hoopy frood
Offline
Hoopy frood
Joined: Oct 2004
Posts: 8,327
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:

Code:
; This will trigger for me
on me:*:text:!news:#: { set %news $?="What is the current news?" }
; This will trigger for everyone else
on *:text:!news:#: { msg $chan %news }


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.


Invision Support
#Invision on irc.irchighway.net
Re: Help File (Documentation) Improvements [Re: Riamus2] #232137 20/05/11 08:02 PM
Joined: Dec 2002
Posts: 2,010
R
RoCk Offline
Hoopy frood
Offline
Hoopy frood
R
Joined: Dec 2002
Posts: 2,010
I'm thinking ON TEXT was a bad example for this since you can't trigger it anyway. smirk

Re: Help File (Documentation) Improvements [Re: RoCk] #232140 20/05/11 10:54 PM
Joined: Oct 2004
Posts: 8,327
Riamus2 Offline
Hoopy frood
Offline
Hoopy frood
Joined: Oct 2004
Posts: 8,327
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. smile


Invision Support
#Invision on irc.irchighway.net
Re: Help File (Documentation) Improvements [Re: csylvain] #232147 21/05/11 01:40 PM
Joined: Sep 2005
Posts: 2,876
H
hixxy Offline
Hoopy frood
Offline
Hoopy frood
H
Joined: Sep 2005
Posts: 2,876
Originally Posted By: csylvain
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.


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?

Originally Posted By: csylvain
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.


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.

Originally Posted By: csylvain
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.


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!

Originally Posted By: csylvain
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?


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:

Code:
//window -d @test | setlayer 150 @test


/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.

Re: Help File (Documentation) Improvements [Re: hixxy] #232215 24/05/11 02:51 AM
Joined: Jan 2011
Posts: 14
C
csylvain Offline OP
Pikka bird
OP Offline
Pikka bird
C
Joined: Jan 2011
Posts: 14
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.

Page 1 of 2 1 2