Documentation

README.md

@@ -1,9 +1,10 @@
 # ReflectionIRCd
 
-ReflectionIRCd is an IRCd that interfaces with Matrix, allowing you to use an IRC client to chat on Matrix.
+ReflectionIRCd is an IRCd that bridges Matrix, allowing you to use an IRC client to chat on Matrix.
 
-This is **very much** not production-ready yet. There's `console.log`s all over the place, no testing or error checking, lots of bugs, etc.
+This is **very much** not production-ready yet. There's `console.log`s all over the place, an inadequate amount of testing and error/bounds checking, several bugs, etc.
-That said, it is usable for basic chatting.
+
+That said, it is usable for basic chatting. See the support matrix (pun intended) below for what it can do.
 
 ## Highlights
 
@@ -12,19 +13,36 @@ That said, it is usable for basic chatting.
 - Built-in bouncer: Multiple IRC clients can be authenticated to a Matrix user
 - Multi-user: Log in to multiple Matrix users at the same time
 
+## FAQs
+
+### Who is this for?
+
+It's for people who want to use their IRC client to chat on Matrix. It's like Bitlbee or Matterbridge, but focused specifically on IRC <-> Matrix, as well as being a reference client for IRCv3 specifications.
+
+It's not meant for community use; if you are a homeserver admin and want to allow your users to use IRC, you would be better off with [heisenbridge](https://github.com/hifi/heisenbridge).
+
+### Why are there different channel prefixes?
+
+Because matrix room names are often long and have characters that IRC channel names can't use, Reflection has to attempt to find a suitable IRC equivalent
+
+`#` channels are channels that have a canonical alias for us to use.
+`&` channels are two-person channels (either DMs or normal channels).
+`!` channels are the room IDs of channels whose names can't be converted into IRC-friendly names.
+
+Note that there are no PMs, because Matrix doesn't differentiate between DMs and normal two-person channels, any channel with two people in it gets marked as a `&` channel.
+
 ## Feature support
 
 ✅ - Implemented  
 🟨 - Partially implemented, see notes  
 ❌ - Not implemented yet  
-⬜ - Not applicable  
 
 <small>(IRCv3)</small> denotes IRC features that might not be available in all clients
 
 | Name | M->I | I->M | Notes |
 | ---- | :--: | :--: | ----- |
-| text, notice, emote messages | ✅ | ✅ ||
+| text, notice, emote messages | ✅ | ✅ | Highlighting users with their IRC nick doesn't translate into highlighting their Matrix user yet |
-| image, file, audio, video messages | 🟨 | ⬜ | Show up as links on IRC |
+| image, file, audio, video messages | 🟨 | ❌ | Show up as links on IRC |
 | Channel joins | ✅ | ❌ ||
 | Channel parts | ✅ | ✅ ||
 | Channel kicks | ✅ | ✅ ||
@@ -32,15 +50,15 @@ That said, it is usable for basic chatting.
 | Channel invites | ✅ | ✅ ||
 | Channel topics | ✅ | ✅ ||
 | Channel powers | ✅ | ❌ ||
-| Channel lists/searching | ⬜ | ❌ ||
+| Channel lists/searching | ❌ | ❌ ||
-| Encrypted rooms | ❌ | ⬜ ||
+| Encrypted rooms | ❌ | ❌ ||
 | Rich text | ❌ | ❌ ||
 | Presence | ❌ | ❌ | Note that not all homeservers have presence enabled |
 | Channel renaming <small>(IRCv3)</small> | 🟨 | ❌ | Only when the canonical alias changes |
 | Message replies <small>(IRCv3)</small> | ✅ | ✅ | Clients without support will still receive the reply message, but it won't be marked as a reply |
 | Message reactions <small>(IRCv3)</small> | 🟨 | 🟨 | Can't undo reactions yet |
 | Extended invites <small>(IRCv3)</small> | ✅ | ✅ ||
-| Chat history <small>(IRCv3)</small> | ⬜ | ❌ ||
+| Chat history <small>(IRCv3)</small> | ❌ | ❌ ||
 | Multiline messages <small>(IRCv3)</small> | ❌ | ❌ ||
 | Global display names <small>(IRCv3)</small> | ❌ | ❌ ||
 | Per-room display names <small>(IRCv3)</small> | ❌ | ❌ ||
@@ -52,3 +70,6 @@ Copy `config.example.json` to `config.json`, edit the values if needed, then `np
 
 ## Authentication
 Authentication is done via `SASL PLAIN`, the username is your mxid and the password is an access token from another session plus your server domain, separated by a `:` (so `access_token:matrix.org` if your server is matrix.org). Note this is the domain for `m.server`, not necessarily the homeserver domain.
+
+## Support
+The main chat is `#reflectionircd` on Libera ([webchat](https://web.libera.chat/gamja/?channel=#reflectionircd)), which is available on Matrix as well at [`#reflectionircd:matrix.org`](https://matrix.to/#/#reflectionircd:matrix.org)

docs/specs/delete-message.md

@@ -1,5 +1,5 @@
 ---
-title: Message Deletion
+title: Message Editing and Deletion
 layout: spec
 work-in-progress: true
 copyrights:
@@ -14,8 +14,8 @@ copyrights:
 This is a work-in-progress specification.
 
 Software implementing this work-in-progress specification MUST NOT use the
-unprefixed `delete-message` capability name. Instead, implementations SHOULD
+unprefixed `edit-message` capability name or `edit-message` and `delete-message` tags. Instead, implementations SHOULD
-use the `draft/delete-message` capability name to be interoperable with other
+use `draft/edit-message` capability and `draft/edit-message` and `draft/delete-message` tags to be interoperable with other
 software implementing a compatible work-in-progress version.
 
 The final version of the specification will use an unprefixed capability name.
@@ -23,20 +23,34 @@ The final version of the specification will use an unprefixed capability name.
 
 ## Introduction
 
-This specification describes a standardized way to signal to clients that a previously
+This specification describes a standardized way to change or delete messages that have been sent.
-sent message should no longer be displayed.
 
 ## Implementation
 
 Servers and clients implementing this spec MUST also implement the `message-tags` capability.
 
+### Message editing
+
+To edit a message, clients send the edited message with a tag of `edit-message`. This tag has a required
+value of the `msgid` from the original message. The edited message MUST have the same command and first
+parameter as the original message, unless it is being changed into a multiline message (see below)
+
+Servers MUST support editing `PRIVMSG`, `NOTICE`, `TAGMSG`, and `PART` messages, and MAY support editing
+any other type of message. Servers SHOULD enforce all checks that they normally would for that specific
+type of message (line length, color stripping, censoring, etc.) and return appropriate numerics if the
+message fails a check.
+
+If the server has any persistent history store for the type of message that is edited, 
+
+To edit a message, clients send an `EDITMSG` tag to the channel or user that the original message was sent to.
+This message MUST have a `draft/target-msgid` tag with a required value of the `msgid` to edit.
 To request message deletion, clients send a `DELETEMSG` to the channel or user of the original message.
-This `DELETEMSG` MUST have the tag `draft/delete-message` with a required value of the `msgid` of the
+This `DELETEMSG` MUST have the tag `draft/target-msgid` with a required value of the `msgid` of the
 message to delete. It MAY have an optional second parameter to specify a reason for deletion.
 
-Clients who receive a `DELETEMSG` with the `draft/delete-message` tag MUST remove all displayed content from
+Clients who receive a `DELETEMSG` with the `draft/target-msgid` tag MUST remove all displayed content from
 the specified `msgid`. If the original message is ephemeral, clients SHOULD remove it entirely;
-otherwise they SHOULD replace it with the deletion reason, or a generic substitute.
+otherwise they MUST replace the content with the deletion reason or a generic substitute.
 
 Servers MUST ensure that the user requesting deletion has sufficient privileges to delete the specified
 message. Servers MUST remove the content of the original message from all persistent history stores, and