From 25077405c2770f47f1531b3a5da0d16e6d36fb9e Mon Sep 17 00:00:00 2001 From: Valentin Lorentz Date: Sun, 19 Sep 2021 12:32:28 +0200 Subject: [PATCH 1/9] Specify the HELP command. With the provision about legacy servers using NOTICE, this seems to cover every IRCd (Bahamut, Ergo, Hybrid/Chary/etc, InspIRCd, irc2, ircu2, ngircd) except Unreal, which uses other numerics. --- _data/modern.yml | 3 ++ _includes/modern-appendix.md | 34 ++++++++++++++++++++++ index.md | 56 ++++++++++++++++++++++++++++++++++++ 3 files changed, 93 insertions(+) diff --git a/_data/modern.yml b/_data/modern.yml index 4aa7a58..d43ad5f 100644 --- a/_data/modern.yml +++ b/_data/modern.yml @@ -668,6 +668,9 @@ numerics: ERR_WHOLIMEXCEED: numeric: '523' + ERR_HELPNOTFOUND: + numeric: '524' + ERR_INVALIDKEY: numeric: '525' diff --git a/_includes/modern-appendix.md b/_includes/modern-appendix.md index fdb8dbd..45335b2 100644 --- a/_includes/modern-appendix.md +++ b/_includes/modern-appendix.md @@ -813,6 +813,14 @@ Indicates that a {% message MODE %} command affecting a user contained a `MODE` Indicates that a {% message MODE %} command affecting a user failed because they were trying to set or view modes for other users. The text used in the last param of this message varies, for instance when trying to view modes for another user, a server may send: `"Can't view modes for other users"`. +{% numericheader ERR_HELPNOTFOUND %} + + " :No help available on this topic" + +Indicates that a {% message HELP %} command requested help on a subject the server does not know about. + +The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. + {% numericheader ERR_INVALIDKEY %} " :Key is not well-formed" @@ -843,6 +851,32 @@ The text used in the last param of this message varies wildly. Indicates that there was a problem with a mode parameter. Replaces various implementation-specific mode-specific numerics. +{% numericheader RPL_HELPSTART %} + + " :" + +Indicates the start of a reply to a {% command HELP %} command to the client. +The text used in the last param of this message may vary, and SHOULD be displayed as-is by IRC clients to their users; possibly emphasized as a the title of the help section. + +The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. + +{% numericheader RPL_HELPTXT %} + + " :" + +When sending a reply to a {% command HELP %} command to the client, servers reply with each line of the help section as this numeric. Help lines MAY be wrapped to 80 characters by the server. + +The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. + +{% numericheader RPL_ENDOFHELP %} + + " :" + +Indicates the end of the reply to the {% command HELP %} command to the client. +The text used in the last param of this message may vary, and SHOULD be shown to the user as any other line. + +The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. + {% numericheader ERR_NOPRIVS %} " :Insufficient oper privileges." diff --git a/index.md b/index.md index 6e9d6af..7e2f8ed 100644 --- a/index.md +++ b/index.md @@ -1228,6 +1228,62 @@ Command Examples: :Wiz STATS c eff.org ; request by WiZ for C/N line information from server eff.org +### HELP message + + Command: HELP + Parameters: [] + +The `HELP` command is used to return documentation about the IRC server and the IRC commands it implements. +When receiving an `HELP` command, servers MUST either: + +1. reply with {% numeric ERR_UNKNOWNCOMMAND %} if they don't support the command at all, +2. reply with a single {% numeric ERR_HELPNOTFOUND %} message if they do not know about the ``, or +3. reply with a single {% numeric RPL_HELPSTART %} message, then arbitrarily many {% numeric RPL_HELPTXT %} messages, then a single {% numeric RPL_ENDOFHELP %}. + +Servers MAY use the third option even on unknown ``; especially if their reply would not fit in a single line. + +It is recommended for the {% numeric RPL_HELPSTART %} message to be some sort of title and for the first {% numeric RPL_HELPTXT %} message to be empty; as if the help was part of a longer document. + +Servers may define any `` they want. +Servers typically have documentation for most of the IRC commands they support. + +Clients SHOULD gracefully handle legacy servers that reply to `HELP` using a set of {% command NOTICE %}. +On these servers, they may try the `HELPOP` command instead (with the same syntax), which may return the numeric-based type of reply. + +Numerics: + +* {% numeric ERR_UNKNOWNCOMMAND %} +* {% numeric ERR_HELPNOTFOUND %} +* {% numeric RPL_HELPSTART %} +* {% numeric RPL_HELPTXT %} +* {% numeric RPL_ENDOFHELP %} + +Command Examples: + + HELP ; request generic help + :server 704 val * :** Help System ** ; first line + :server 705 val * : + :server 705 val * :Try /HELP for specific help, + :server 705 val * :/HELP USERCMDS to list available + :server 706 val * :commands, or join the #help channel ; last line + + HELP PRIVMSG ; request help on PRIVMSG + :server 704 val PRIVMSG :** The PRIVMSG command ** + :server 705 val PRIVMSG : + :server 705 val PRIVMSG :The /PRIVMSG command is the main way + :server 706 val PRIVMSG :to send messages to other users. + + HELP :unknown subject ; request help on "unknown subject" + :server 524 val * :I do not know anything about this + + HELP :unknown subject + :server 704 val * :** Help System ** + :server 705 val * : + :server 705 val * :I do not know anything about this. + :server 705 val * : + :server 705 val * :Try /HELP USERCMDS to list available + :server 706 val * :commands, or join the #help channel + ### INFO message Command: INFO From eebdf683c317af712d0a6aa3dced4d5e505fa685 Mon Sep 17 00:00:00 2001 From: Val Lorentz Date: Sun, 19 Sep 2021 14:00:21 +0200 Subject: [PATCH 2/9] Update index.md Co-authored-by: Daniel Oaks --- index.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/index.md b/index.md index 7e2f8ed..c804814 100644 --- a/index.md +++ b/index.md @@ -1234,25 +1234,19 @@ Command Examples: Parameters: [] The `HELP` command is used to return documentation about the IRC server and the IRC commands it implements. -When receiving an `HELP` command, servers MUST either: -1. reply with {% numeric ERR_UNKNOWNCOMMAND %} if they don't support the command at all, -2. reply with a single {% numeric ERR_HELPNOTFOUND %} message if they do not know about the ``, or -3. reply with a single {% numeric RPL_HELPSTART %} message, then arbitrarily many {% numeric RPL_HELPTXT %} messages, then a single {% numeric RPL_ENDOFHELP %}. +When receiving a `HELP` command, servers MUST either: reply with a single {% numeric ERR_HELPNOTFOUND %} message; or reply with a single {% numeric RPL_HELPSTART %} message, then arbitrarily many {% numeric RPL_HELPTXT %} messages, then a single {% numeric RPL_ENDOFHELP %}. Servers MAY return the {% numeric RPL_HELPTXT %} form for unknown subjects, especially if their reply would not fit in a single line. -Servers MAY use the third option even on unknown ``; especially if their reply would not fit in a single line. +The {% numeric RPL_HELPSTART %} message SHOULD be some sort of title and the first {% numeric RPL_HELPTXT %} message SHOULD be empty. This is what most servers do today. -It is recommended for the {% numeric RPL_HELPSTART %} message to be some sort of title and for the first {% numeric RPL_HELPTXT %} message to be empty; as if the help was part of a longer document. - -Servers may define any `` they want. +Servers MAY define any `` they want. Servers typically have documentation for most of the IRC commands they support. -Clients SHOULD gracefully handle legacy servers that reply to `HELP` using a set of {% command NOTICE %}. -On these servers, they may try the `HELPOP` command instead (with the same syntax), which may return the numeric-based type of reply. +Clients SHOULD gracefully handle older servers that reply to `HELP` with a set of {% command NOTICE %} messages. +On these servers, the client may try sending the `HELPOP` command (with the same syntax specified here), which may return the numeric-based reply. Numerics: -* {% numeric ERR_UNKNOWNCOMMAND %} * {% numeric ERR_HELPNOTFOUND %} * {% numeric RPL_HELPSTART %} * {% numeric RPL_HELPTXT %} From e3ef4019296480b21fad58b0858e3bdf5f5a4899 Mon Sep 17 00:00:00 2001 From: Val Lorentz Date: Sun, 19 Sep 2021 14:00:33 +0200 Subject: [PATCH 3/9] Update _includes/modern-appendix.md Co-authored-by: Daniel Oaks --- _includes/modern-appendix.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_includes/modern-appendix.md b/_includes/modern-appendix.md index 45335b2..84979ca 100644 --- a/_includes/modern-appendix.md +++ b/_includes/modern-appendix.md @@ -853,12 +853,12 @@ Indicates that there was a problem with a mode parameter. Replaces various imple {% numericheader RPL_HELPSTART %} - " :" + " :" -Indicates the start of a reply to a {% command HELP %} command to the client. +Indicates the start of a reply to a {% command HELP %} command. The text used in the last param of this message may vary, and SHOULD be displayed as-is by IRC clients to their users; possibly emphasized as a the title of the help section. -The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. +The `` MUST be the one requested by the client, but may be casefolded; unless it would be an invalid parameter, in which case it MUST be `*`. {% numericheader RPL_HELPTXT %} From fac1636bd3b435620f852ea984e08fa89667493c Mon Sep 17 00:00:00 2001 From: Val Lorentz Date: Sun, 19 Sep 2021 14:16:44 +0200 Subject: [PATCH 4/9] Update _includes/modern-appendix.md Co-authored-by: Daniel Oaks --- _includes/modern-appendix.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/_includes/modern-appendix.md b/_includes/modern-appendix.md index 84979ca..0337e46 100644 --- a/_includes/modern-appendix.md +++ b/_includes/modern-appendix.md @@ -872,8 +872,7 @@ The `` MUST be the one requested by the client, up to casing; unless it " :" -Indicates the end of the reply to the {% command HELP %} command to the client. -The text used in the last param of this message may vary, and SHOULD be shown to the user as any other line. +Returns the final {% command HELP %} line to the client. The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. From d9e68734d588abef35a030779f1daf00a7558ce6 Mon Sep 17 00:00:00 2001 From: Val Lorentz Date: Sun, 19 Sep 2021 14:39:36 +0200 Subject: [PATCH 5/9] Update _includes/modern-appendix.md Co-authored-by: Daniel Oaks --- _includes/modern-appendix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_includes/modern-appendix.md b/_includes/modern-appendix.md index 0337e46..e43078f 100644 --- a/_includes/modern-appendix.md +++ b/_includes/modern-appendix.md @@ -864,7 +864,7 @@ The `` MUST be the one requested by the client, but may be casefolded; " :" -When sending a reply to a {% command HELP %} command to the client, servers reply with each line of the help section as this numeric. Help lines MAY be wrapped to 80 characters by the server. +Returns a line of {% command HELP %} text to the client. Lines MAY be wrapped to a certain line length by the server. Note that the final line MUST be a {% numeric RPL_ENDOFHELP %} numeric. The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. From e0d31e4a00ac4eec87a1261af9101b083a92bbe6 Mon Sep 17 00:00:00 2001 From: Val Lorentz Date: Sat, 6 Nov 2021 09:50:17 +0100 Subject: [PATCH 6/9] Update _includes/modern-appendix.md Co-authored-by: tommyrot --- _includes/modern-appendix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_includes/modern-appendix.md b/_includes/modern-appendix.md index e43078f..c19b064 100644 --- a/_includes/modern-appendix.md +++ b/_includes/modern-appendix.md @@ -856,7 +856,7 @@ Indicates that there was a problem with a mode parameter. Replaces various imple " :" Indicates the start of a reply to a {% command HELP %} command. -The text used in the last param of this message may vary, and SHOULD be displayed as-is by IRC clients to their users; possibly emphasized as a the title of the help section. +The text used in the last parameter of this message may vary, and SHOULD be displayed as-is by IRC clients to their users; possibly emphasized as the title of the help section. The `` MUST be the one requested by the client, but may be casefolded; unless it would be an invalid parameter, in which case it MUST be `*`. From 9f4fc47eb52c3e9890d795c9d90f31bf3ba82097 Mon Sep 17 00:00:00 2001 From: Val Lorentz Date: Sat, 6 Nov 2021 09:50:28 +0100 Subject: [PATCH 7/9] Update _includes/modern-appendix.md Co-authored-by: Daniel Oaks --- _includes/modern-appendix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_includes/modern-appendix.md b/_includes/modern-appendix.md index c19b064..5760fdf 100644 --- a/_includes/modern-appendix.md +++ b/_includes/modern-appendix.md @@ -819,7 +819,7 @@ Indicates that a {% message MODE %} command affecting a user failed because they Indicates that a {% message HELP %} command requested help on a subject the server does not know about. -The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. +The `` MUST be the one requested by the client, but may be casefolded; unless it would be an invalid parameter, in which case it MUST be `*`. {% numericheader ERR_INVALIDKEY %} From 95dca4831eb2874eb11fa22764b5311a9958ba6e Mon Sep 17 00:00:00 2001 From: Val Lorentz Date: Sat, 6 Nov 2021 09:50:42 +0100 Subject: [PATCH 8/9] Update _includes/modern-appendix.md Co-authored-by: Daniel Oaks --- _includes/modern-appendix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_includes/modern-appendix.md b/_includes/modern-appendix.md index 5760fdf..3e8d0c5 100644 --- a/_includes/modern-appendix.md +++ b/_includes/modern-appendix.md @@ -866,7 +866,7 @@ The `` MUST be the one requested by the client, but may be casefolded; Returns a line of {% command HELP %} text to the client. Lines MAY be wrapped to a certain line length by the server. Note that the final line MUST be a {% numeric RPL_ENDOFHELP %} numeric. -The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. +The `` MUST be the one requested by the client, but may be casefolded; unless it would be an invalid parameter, in which case it MUST be `*`. {% numericheader RPL_ENDOFHELP %} @@ -874,7 +874,7 @@ The `` MUST be the one requested by the client, up to casing; unless it Returns the final {% command HELP %} line to the client. -The `` MUST be the one requested by the client, up to casing; unless it would be an invalid parameter, in which case it MUST be `*`. +The `` MUST be the one requested by the client, but may be casefolded; unless it would be an invalid parameter, in which case it MUST be `*`. {% numericheader ERR_NOPRIVS %} From 592e8c3b5b8346383c09a4b8df39559079ba1463 Mon Sep 17 00:00:00 2001 From: Valentin Lorentz Date: Sat, 20 Nov 2021 20:45:27 +0100 Subject: [PATCH 9/9] Mention Unreal-style replies to the HELP command Unreal uses only 290 and 292, but names all numerics from 290 to 295; so it must be based on something else that uses all of them. Additionally, based on the names Unreal uses, it should be using 291 instead of 292, so it really does not make sense to me. --- index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/index.md b/index.md index c804814..cfd426e 100644 --- a/index.md +++ b/index.md @@ -1245,6 +1245,8 @@ Servers typically have documentation for most of the IRC commands they support. Clients SHOULD gracefully handle older servers that reply to `HELP` with a set of {% command NOTICE %} messages. On these servers, the client may try sending the `HELPOP` command (with the same syntax specified here), which may return the numeric-based reply. +Clients SHOULD also gracefully handle servers that reply to `HELP` with a set of `290`/`291`/`292`/`293`/`294`/`295` numerics. + Numerics: * {% numeric ERR_HELPNOTFOUND %}