ircdocs / irc-defs Goto Github PK

View Code? Open in Web Editor NEW

61.0 9.0 19.0 470 KB

More up-to-date IRC Definition Lists

Home Page: http://defs.ircdocs.horse/

License: Creative Commons Zero v1.0 Universal

Python 30.82% HTML 68.90% Ruby 0.28%

irc irc-protocol

irc-defs's Introduction

IRC Definition Lists

These are IRC definition lists. Things like lists of IRC numerics, channel modes, user modes and other things that are implemented in various bits of IRC software.

Base data was taken from alien.net.au, converted to YAML via the tools in the _legacy_data/ folder and adapted for use with the Jekyll static site generator (used by Github Pages).

Pull requests to correct or update these lists are welcomed.

Online Site: https://defs.ircdocs.horse/

Available Pages

Repo Structure

Given that this is a Jekyll site, there's a very particular way this repo is laid out, which I'll go through here:

_data/ - contains the data files, which make up our tables;
- validation/ - contains validation files, which yamltypes uses to validate the data files;
- chanmembers.yaml - data for Channel Member Prefixes;
- chanmodes.yaml - data for Channel Modes;
- chantypes.yaml - data for Channel Type Prefixes;
- clientcaps.yaml - data for Client Capabilities;
- ctcp.yaml - data for CTCP Messages;
- extbans.yaml - data for Extended Bans (banning/excluding by account, etc.);
- formatting.yaml - data for Formatting Characters support in different clients;
- isupport.yaml - data for RPL_ISUPPORT Tokens;
- numerics.yaml - data for Numerics;
- selfmessage.yaml - data for self-message support in different clients;
- servermodes.yaml - data for Server Modes;
- snomasks.yaml - data for Server Notice Masks;
- stats.yaml - data for STATS Characters;
- tags.yaml - data for Message Tags;
- usermodes.yaml - data for User Modes;
_includes/ - contains Jekyll HTML includes;
- table.html - this is the main data-table printer, outputs based on the content of the YAML data files;
_layouts/ - contains Jekyll HTML layouts;
_legacy_data/ - contains the original data files from alient.net.au, which we used, along with our original conversion script;
defs/ - contains the front-end HTML for each definitions page;
discover_numerics - script to discover numerics for various IRC servers from their source repo.

YAML Structure

To interpret YAML data files:

//TODO

License

The following license information is from the alien.net.au website:

You may be interested in using the definition files in your own project;
There are no license restrictions, other than to retain the copyright information.

Copyright information is listed in the specific converted spec files in the _data/ folder (as in the original .def files downloaded from alien.net.au).

Discovering Numerics

I've written a script called discover_numerics that helps me search for numerics that aren't currently listed in our list. It's helpful to use this to search new releases of ircd-hybrid, inspircd, charybdis, unrealircd, etc.

It requires the pyyaml and docopt python modules. To install the required modules, install python3-pip, then run:

pip3 install pyyaml docopt

Usage Examples

Searching a typical `numeric.h` file

Searching a single numeric.h file, such as in ircd-hybrid, charybdis, unrealircd, etc:

./discover_numerics search /path/to/ircd/include/numerics.h

Searching InspIRCd

Because inspircd scatters its numeric definitions all over its source directory, you can't just search a single file. Because of this, you need to search multiple files in the directory like this:

find /path/to/inspircd/ -type f | xargs ./discover_numerics search

This also does not find every numeric, thanks to how inspircd likes to use numerics directly rather than #define them.

Numerics will output as lines like this, which makes it simple to grep through the source directory to discover the format and usage of these numerics:

Could not find numeric: RPL_STATSCLONE (225)
Could not find numeric: RPL_USINGSSL (275)
Could not find numeric: RPL_EXEMPTLIST (348)
Could not find numeric: RPL_ENDOFEXEMPTLIST (349)
Could not find numeric: RPL_RWHOREPLY (354)
Could not find numeric: ERR_TARGETTOFAST (439)
Could not find numeric: ERR_NOSSL (488)
Could not find numeric: ERR_NOSHAREDCHAN (493)
Could not find numeric: ERR_LAST_ERR_MSG (504)

irc-defs's People

Contributors

Stargazers

Watchers

Forkers

dequis jwheare joeyrp prawnsalad slingamn digitalcircuit trobotham justjanne doc22940 koragg-irc-docu hhirtz progval emersion octota-github qpc-github mokou funderscore1 tommyrot

irc-defs's Issues

Document using discover_numerics script

It shouldn't be to difficult to get into using, but it would be nice to add some docs to the README for running the script.

Describe users rather than origin

Rather than 'origin' being the useful bit of info, we should describe who uses the given mode/etc.

E.g. maybe something along these lines:

Universal: Everyone uses this one.
Universal except ...: When it's universal except a couple outliers.
<list of software>: When it's less than almost-universal.

Esp for conflicts this'd be a lot better than the current state of only one impl listed for each with no way to tell how widespread one is over the other.

Create new [ctcp] list

Containing the full (extended) list of params from https://gist.github.com/grawity/a74722bfbfc3957684e0 and defined by other software, since I'm likely going to leave a few out when I throw that spec itself up on Modern.

AdiIRC supports Ctrl+E strikethough since Sept 2021

https://defs.ircdocs.horse/info/formatting.html

https://adiirc.com/changelog.php?v=0

4.1 Beta Build (2021/09/22 UTC)
Add support for strikethrough control character

(Full versions 4.1 and 4.2 have released since then)

TBD: find someone who knows why the horse docs doesn't think anyone supports ^O reset

[chanmembers] List multiple prefixes explicitly

We should list multiple prefixes in the chanmembers list explicitly, as discussed in #5.

ie, YAML:

- ['a', '&']
- ['a', '!']

...

- ['q', '~']
- ['y', '~']

HTML, with all the modes listed in the same row as the name, just on new lines (blame Github markdown for them being in separate rows):

Name	Mode
PROTECTED	`(a)&`
	`(a)!`
OWNER	`(q)~`
	`(y)~`

Similar to how they're displayed in the PREFIX token on ISUPPORT.

Create table looking at how clients handle NOTICEs

Common wisdom is that clients handle NOTICEs to messages VERY BADLY. Like, NEVER DO THIS. You can get banned from channels and networks for it.

Especially one claim in particular, clients will treat any NOTICE to a channel like a ping.

We should look into how clients treat notices, and notices to channels in particular. Whether they use a different appearance for them vs just displaying them like a normal privmsg, etc etc. It's definitely true that the original purpose of them ('a privmsg that bots don't respond to') is no longer accurate, but how not-accurate is it?

Setup Travis to scan this again

Seems the scanning messed up when I switched this from DanielOaks/irc-defs to ircdocs/irc-defs, just need to go into Travis, confirm it has rights here and set it up again.

mIRC supports strikethough since v7.68

https://defs.ircdocs.horse/info/formatting.html

https://forums.mirc.com/ubbthreads.php/topics/270108/mirc-7-68-released

Added support for strikethrough text using Control+E.

Mark specific IRCds as deprecated?

IRCds that haven't been updated in ages and which are not used in the real world should have their numerics marked as 'obsolete' if they are not used by other IRCds, imo. This is a list of IRCds which I'm thinking about marking obsolete, and would like some comments and thoughts on:

Ithildin: hasn't been updated in quite a while, and I can't see it used anywhere.

make colours accessible

put pattern behind the thing so that peeps with colour blindness can also read the tables. use this or something

RPL_TRACE* numerics missing details

It is difficult to tell what the parameters for these numerics mean. It would be nice to know what sort of values clients can expect.

Create new [extbans] list

We should create a list of the different types of extbans that are provided by ircds, and the characters used for them.

Replace 'revision' with just the build date

I think this is relatively sensible? Feels a bit outdated and mostly a carryover from the alien lists. We can't get the latest commit date, can we?

EXTBAN example missing prefix

One of the EXTBAN examples in the RPL_ISUPPORT tokens doc is missing a prefix character. However, the description for the token does not explain how a client is meant to interpret this case.

Client Capabilities page

We should have a page listing client capabilities, similar to the RPL_ISUPPORT page.

Typo in numerics.yaml

I think there's a typo on line 3822. RPL_ENDOFO<MOTD looks like it should just be RPL_ENDOFO.

[ircnumerics] rename to [numerics]

'ircnumerics' was mostly used just because of the legacy name of the file, we should change this over now and continue to provide 'ircnumerics.html' for things that link to it.

list of verbs

Requested: A list of commands/messages, the spec that introduced them, whether it's one a client sends or a client receives (or both), etc.

Graphically describe legends for table colours

Tables and graphs with multiple colours usually have a table showing colors and their meanings. I think switching to a tabular legend would make interpretations on the defs tables more obvious. If that is too complicated, at least adding the relevant color behind the corresponding words (ie "Red", etc.) should improve readability.

[ircnumerics] Convert IDs to use name-numeric

Instead of linking just to http://defs.ircdocs.horse/defs/ircnumerics.html#005 , links should be provided for http://defs.ircdocs.horse/defs/ircnumerics.html#rplisupport-005 and http://defs.ircdocs.horse/defs/ircnumerics.html#rplbounce-005 , similar to how numerics are linked here

Figure out where ERR_UNKNOWNERROR (400) came from

I have no clue what first defined this numeric or where it came from. It's not in the RFCs, it's not in irc2, unreal, ircu, insp. But it is in the original alien lists. Maybe they defined it but it feels like it would've come with an AustHex or the like tag in the origin column if they did.

Search through the old mailing list archives, see the first time it pops up in there.

[numerics] Initial <client>/<nick> param should be in format

The first param of most numerics is the nick of the currently connected client. So, the initial lists skipped adding this first numeric (also seen in the RFCs). However, this isn't the case for all of them these days.

The numerics list should include this first client name parameter. I did it as <client> in the Modern document (seen in that format block underneath each numeric name), but however we want to do it is fine. So long as it doesn't get confused with the actual numeric-specific parameters.