diff --git a/docs/irc/formatting.md b/docs/irc/formatting.md deleted file mode 100644 index e1bb5541656273f57a68d776f9eccfb3db95d190..0000000000000000000000000000000000000000 --- a/docs/irc/formatting.md +++ /dev/null @@ -1,458 +0,0 @@ -# Formatting - -!!! info - This page is adapted and extended from http://modern.ircdocs.horse/formatting.html, https://www.mirc.com/colors.html - and http://m8y.org/tmp/extended_mirc_color_proposal.html - -!!! summary "Authors" - **Original Creator** - [Daniel Oaks](http://ircdocs.horse/) - http://modern.ircdocs.horse/formatting.html - *daniel@danieloaks.net* - - **Adapted and Extended By** - [Janne Koschinski](https://kuschku.de/) - *support@kuschku.de* - -!!! warning - This document describes the current situation of what clients implement. It is therefore subject to change, and - should not be understood as strict specification. - - In case of mistakes, please [contact me](mailto:support@kuschku.de). - - -## Introduction - -IRC clients today understand a number of special formatting characters. These characters allow IRC software to send and -receive colors and formatting codes such as bold, italics, underline and others. - -Over the years, many clients have attempted to create their own methods of formatting and there have been variations and -extensions of almost every method. However, the characters and codes described in this document are understood fairly -consistently across clients today. - -Following what's described in this document should let your software send and interpret formatting in a fairly sane way, -consistent with how most other IRC software out there does. Using formatting characters and methods not described in -this document is possible, but it should be assumed they will not work across most clients (unless there is some way to -fall back to what's defined here). - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and -"OPTIONAL" in this document are to be interpreted as described in [RFC2119](http://tools.ietf.org/html/rfc2119). - - ---- - - -## Formatting Uses - -Formatting is widely used in IRC. In this section, we outline the places where formatting is traditionally used by -clients and allowed by servers. This is not an expansive list nor does it note everywhere formatting is used, just some -of the most common places. - - -### Messages / Numerics - -Formatting characters can be used in lots of IRC messages and numerics. This is not a complete list, just some of the -messages formatting codes are used with most often. - -These are some of the messages and features formatting codes are normally used with: - -* [`PRIVMSG`](/index.html#privmsg-message) -* [`NOTICE`](/index.html#notice-message) -* [`TOPIC`](/index.html#topic-message) -* [`AWAY`](/index.html#away-message) -* [`USER`](/index.html#user-message) (allowed in realnames, **not** in usernames) -* The [Message of the Day](/index.html#motd-message) - -And the numerics containing content associated with these messages and features. - - -### Names - -Formatting is allowed and commonly used in realnames (set with the [`USER`](/index.html#user-message) command when the -client joins the network). - -On some networks and with some server software, vhosts (vanity hostnames) may contain formatting characters and codes. -Hostnames sent to clients MAY contain formatting, and clients SHOULD display them with this in mind. - -The use of formatting MUST NOT be allowed in nicknames, user names or channel names. This is to avoid confusion and -prevent issues, particularly with clients that have disabled the rendering of colors / formatting or cannot display -certain types of formatting. - -If a client sends a [`USER`](/index.html#user-message) command with any formatting codes in the first parameter (in the -username) during registration, the server SHOULD send the client an [`ERROR`](/index.html#error-message) message and -close the connection. - - ---- - - -## Client Behaviour - -This section is non-normative and outlines suggested behaviour for clients and client interfaces. - - -### Limitations - -If an IRC client cannot display a specified type of formatting, the client should do one of the following: - -* Simply not display the formatting. -* Display the formatting character in an obvious way, so users are aware that it was used. - -One way some clients represent formatting characters they cannot display is using an uppercase letter which represents -the specific formatting character, with their default foreground and background colors switched. For example, displaying -an underline formatting character as <span class="reverse">U</span>. - - -### Preventing Display of Formatting - -Clients may allow users to prevent all or just specified formatting from displaying. This can help users that are -colorblind or are visually impaired, and should be considered by client authors. - - -### ANSI Escape Code Support - -IRC clients supporting ANSI formatting was, historically, due to clients outputting messages via terminals that -supported ANSI escape codes. Many IRC clients today do not display through an interface that natively supports ANSI -escape codes, and so must implement this behaviour themselves if they wish to support it. - -Clients can support or not support ANSI escape codes as they like. However, they should implement this feature with the -knowledge that a large number of IRC clients today, even those using a terminal interface, do not support displaying -text formatted using ANSI escape codes. - - ---- - - -## Characters - -There are a number of formatting characters that are parsed and understood by IRC software today. - -Some formatting codes work as a toggle, i.e. with the first instance of the character, the specified formatting is -enabled for the following text. After the next instance of that character, that formatting is disabled for the following -characters. Formatting codes that work in this way are called 'togglable'. - -These formatting characters are the ones all IRC clients should understand. - -### Bold - -`ASCII 0x02` - -This formatting character works as a toggle. It enables bold text (e.g. **bold text**). - -### Italics - -`ASCII 0x1D` - -This formatting character works as a toggle. It enables italicized text (e.g. *italicised text*). - -### Underline - -`ASCII 0x1F` - -This formatting character works as a toggle. It enables underlined text (e.g. ^^underlined text^^). - -### Strikethrough - -`ASCII 0x1E` - -This formatting character works as a toggle. It enables strikethrough'd text (e.g. ~~strokethrough text~~). - -This character is a relatively new addition, and was defined by Textual (as of right now, Textual's the only client that -understands this character). However, if you do add strikethrough capabilities within your client, please use this -character as it is already defined and in use. - -### Monospace - -`ASCII 0x11` - -This formatting character works as a toggle. It enables monospace'd text (e.g. `monospace text`). - -This character is a relatively new addition, and was defined by IRCCloud (as of right now, IRCCloud's the only client -that understands this character). However, if you do add monospace capabilities within your client, please use this -character as it is already defined and in use. - -### Color - -`ASCII 0x03` - -This formatting character sets or resets colors on the following text. - -With this formatting code, colors are represented as ASCII digits. - -#### Forms of Color Codes - -In the following list, `<CODE>` represents the color formatting character `(0x03)`, `<COLOR>` represents one or two -ASCII digits (either `0—9` or `00—15`). - -The use of this code can take on the following forms: - -* `<CODE>` - Reset foreground and background colors. -* `<CODE>,` - Reset foreground and background colors and display the `,` character as text. -* `<CODE><COLOR>` - Set the foreground color. -* `<CODE><COLOR>,` - Set the foreground color and display the `,` character as text. -* `<CODE><COLOR>,<COLOR>` - Set the foreground and background color. - -The foreground color is the first `<COLOR>`, and the background color is the second `<COLOR>` (if sent). - -If only the foreground color is set, the background color stays the same. - -!!! warning - If there are two ASCII digits available where a `<COLOR>` is allowed, if the two characters are in the range `00—15` - then two characters MUST always be read for it. If they are in the range `16—99`, the client MAY unconditionally - read and process the two characters, or the client MAY read just the first digit and display the second digit. - - Clients SHOULD NOT send the digits `16—99` where a `<COLOR>` is allowed, as clients will interpret it differently. - -#### Colors - -The following colors are defined for use with this formatting character: - -* <tt><span irc_background=0> </span> - 00</tt> - White. -* <tt><span irc_background=1> </span> - 01</tt> - Black. -* <tt><span irc_background=2> </span> - 02</tt> - Blue. -* <tt><span irc_background=3> </span> - 03</tt> - Green. -* <tt><span irc_background=4> </span> - 04</tt> - Red. -* <tt><span irc_background=5> </span> - 05</tt> - Brown. -* <tt><span irc_background=6> </span> - 06</tt> - Magenta. -* <tt><span irc_background=7> </span> - 07</tt> - Orange. -* <tt><span irc_background=8> </span> - 08</tt> - Yellow. -* <tt><span irc_background=9> </span> - 09</tt> - Light Green. -* <tt><span irc_background=10> </span> - 10</tt> - Cyan. -* <tt><span irc_background=11> </span> - 11</tt> - Light Cyan. -* <tt><span irc_background=12> </span> - 12</tt> - Light Blue. -* <tt><span irc_background=13> </span> - 13</tt> - Pink. -* <tt><span irc_background=14> </span> - 14</tt> - Grey. -* <tt><span irc_background=15> </span> - 15</tt> - Light Grey. -* <tt><span irc_background=1> </span><span irc_background=0> </span> - 99</tt> - - Default Foreground/Background - Not universally supported. - -!!! note - The colors displayed here are simply a guide. The actual RGB values used for these codes will depend on what the - client author has defined, and are often defined by the terminal color scheme for terminal-based clients. - -#### Extended Colors - -!!! warning - The color codes `16—99` will be interpreted different ways by different clients, and we do not recommend using them. - However, if you do add support for them within your client, please use the following definitions, as they are - already defined and in use. - -<table> - <tr> - <th>15—20</th> - <td/> - <td><tt><span irc_background=16> </span> #470000</tt></td> - <td><tt><span irc_background=17> </span> #472100</tt></td> - <td><tt><span irc_background=18> </span> #474700</tt></td> - <td><tt><span irc_background=19> </span> #324700</tt></td> - </tr> - <tr> - <th>20—25</th> - <td><tt><span irc_background=20> </span> #004700</tt></td> - <td><tt><span irc_background=21> </span> #00472c</tt></td> - <td><tt><span irc_background=22> </span> #004747</tt></td> - <td><tt><span irc_background=23> </span> #002747</tt></td> - <td><tt><span irc_background=24> </span> #000047</tt></td> - </tr> - <tr> - <th>25—30</th> - <td><tt><span irc_background=25> </span> #2e0047</tt></td> - <td><tt><span irc_background=26> </span> #470047</tt></td> - <td><tt><span irc_background=27> </span> #47002a</tt></td> - <td><tt><span irc_background=28> </span> #740000</tt></td> - <td><tt><span irc_background=29> </span> #743a00</tt></td> - </tr> - <tr> - <th>30—35</th> - <td><tt><span irc_background=30> </span> #747400</tt></td> - <td><tt><span irc_background=31> </span> #517400</tt></td> - <td><tt><span irc_background=32> </span> #007400</tt></td> - <td><tt><span irc_background=33> </span> #007449</tt></td> - <td><tt><span irc_background=34> </span> #007474</tt></td> - </tr> - <tr> - <th>35—40</th> - <td><tt><span irc_background=35> </span> #004074</tt></td> - <td><tt><span irc_background=36> </span> #000074</tt></td> - <td><tt><span irc_background=37> </span> #4b0074</tt></td> - <td><tt><span irc_background=38> </span> #740074</tt></td> - <td><tt><span irc_background=39> </span> #740045</tt></td> - </tr> - <tr> - <th>40—45</th> - <td><tt><span irc_background=40> </span> #b50000</tt></td> - <td><tt><span irc_background=41> </span> #b56300</tt></td> - <td><tt><span irc_background=42> </span> #b5b500</tt></td> - <td><tt><span irc_background=43> </span> #7db500</tt></td> - <td><tt><span irc_background=44> </span> #00b500</tt></td> - </tr> - <tr> - <th>45—50</th> - <td><tt><span irc_background=45> </span> #00b571</tt></td> - <td><tt><span irc_background=46> </span> #00b5b5</tt></td> - <td><tt><span irc_background=47> </span> #0063b5</tt></td> - <td><tt><span irc_background=48> </span> #0000b5</tt></td> - <td><tt><span irc_background=49> </span> #7500b5</tt></td> - </tr> - <tr> - <th>50—55</th> - <td><tt><span irc_background=50> </span> #b500b5</tt></td> - <td><tt><span irc_background=51> </span> #b5006b</tt></td> - <td><tt><span irc_background=52> </span> #ff0000</tt></td> - <td><tt><span irc_background=53> </span> #ff8c00</tt></td> - <td><tt><span irc_background=54> </span> #ffff00</tt></td> - </tr> - <tr> - <th>55—60</th> - <td><tt><span irc_background=55> </span> #b2ff00</tt></td> - <td><tt><span irc_background=56> </span> #00ff00</tt></td> - <td><tt><span irc_background=57> </span> #00ffa0</tt></td> - <td><tt><span irc_background=58> </span> #00ffff</tt></td> - <td><tt><span irc_background=59> </span> #008cff</tt></td> - </tr> - <tr> - <th>60—65</th> - <td><tt><span irc_background=60> </span> #0000ff</tt></td> - <td><tt><span irc_background=61> </span> #a500ff</tt></td> - <td><tt><span irc_background=62> </span> #ff00ff</tt></td> - <td><tt><span irc_background=63> </span> #ff0098</tt></td> - <td><tt><span irc_background=64> </span> #ff5959</tt></td> - </tr> - <tr> - <th>65—70</th> - <td><tt><span irc_background=65> </span> #ffb459</tt></td> - <td><tt><span irc_background=66> </span> #ffff71</tt></td> - <td><tt><span irc_background=67> </span> #cfff60</tt></td> - <td><tt><span irc_background=68> </span> #6fff6f</tt></td> - <td><tt><span irc_background=69> </span> #65ffc9</tt></td> - </tr> - <tr> - <th>70—75</th> - <td><tt><span irc_background=70> </span> #6dffff</tt></td> - <td><tt><span irc_background=71> </span> #59b4ff</tt></td> - <td><tt><span irc_background=72> </span> #5959ff</tt></td> - <td><tt><span irc_background=73> </span> #c459ff</tt></td> - <td><tt><span irc_background=74> </span> #ff66ff</tt></td> - </tr> - <tr> - <th>75—80</th> - <td><tt><span irc_background=75> </span> #ff59bc</tt></td> - <td><tt><span irc_background=76> </span> #ff9c9c</tt></td> - <td><tt><span irc_background=77> </span> #ffd39c</tt></td> - <td><tt><span irc_background=78> </span> #ffff9c</tt></td> - <td><tt><span irc_background=79> </span> #e2ff9c</tt></td> - </tr> - <tr> - <th>80—85</th> - <td><tt><span irc_background=80> </span> #9cff9c</tt></td> - <td><tt><span irc_background=81> </span> #9cffdb</tt></td> - <td><tt><span irc_background=82> </span> #9cffff</tt></td> - <td><tt><span irc_background=83> </span> #9cd3ff</tt></td> - <td><tt><span irc_background=84> </span> #9c9cff</tt></td> - </tr> - <tr> - <th>85—90</th> - <td><tt><span irc_background=85> </span> #dc9cff</tt></td> - <td><tt><span irc_background=86> </span> #ff9cff</tt></td> - <td><tt><span irc_background=87> </span> #ff94d3</tt></td> - <td><tt><span irc_background=88> </span> #000000</tt></td> - <td><tt><span irc_background=89> </span> #131313</tt></td> - </tr> - <tr> - <th>90—95</th> - <td><tt><span irc_background=90> </span> #282828</tt></td> - <td><tt><span irc_background=91> </span> #363636</tt></td> - <td><tt><span irc_background=92> </span> #4d4d4d</tt></td> - <td><tt><span irc_background=93> </span> #656565</tt></td> - <td><tt><span irc_background=94> </span> #818181</tt></td> - </tr> - <tr> - <th>95—100</th> - <td><tt><span irc_background=95> </span> #9f9f9f</tt></td> - <td><tt><span irc_background=96> </span> #bcbcbc</tt></td> - <td><tt><span irc_background=97> </span> #e2e2e2</tt></td> - <td><tt><span irc_background=98> </span> #ffffff</tt></td> - <td/> - </tr> -</table> - -#### Mistaken Eating of Text - -When sending color codes `0—9`, clients may use either the one-digit `(3)` or two-digit `(03)` versions of it. However, -since two digits are always used if available, if the text following the color code starts with a digit, the last -`<COLOR>` MUST use the two-digit version to be displayed correctly. This ensures that the first character of the text -does not get interpreted as part of the formatting code. - -If the text immediately following a code setting a foreground color consists of something like `",13"`, it will get -interpreted as setting the background rather than text. In this example, clients can put the color code either after the -comma character or before the character in front of the comma character to avoid this. They can also put a different -formatting code after the comma to ensure that the number does not get interpreted as part of the color code (for -instance, two bold characters in a row, which will cancel each other out as they are toggles). - - -### Hex Color - -`ASCII 0x04` - -Some clients support an alternate form of conveying colors using hex codes. - -Following this character are six hex digits representing the Red, Green and Blue values of the color to display (e.g. -`FF0000` means <span style="color:#ff0000">bright red</span>). - -Keep the [Forms of Color Codes](#forms-of-color-codes) section above in mind, as this method of formatting keeps these -same rules – the exceptions being that `<CODE>` represents the hex color character `(0x04)` and `<COLOR>` represents a -six-digit hex value as `RRGGBB`. - -This method of formatting is not as widely-supported as the colors above, but clients are fine to parse them without any -negative effects. - - -### Reverse Color - -`ASCII 0x16` - -This formatting character works as a toggle. When reverse color is enabled, the foreground and background text colors -are reversed. For instance, if you enable reverse color and then send the line -"<span class="reverse">C</span>3,13Test!", you will end up with pink foreground text and green background text while the -reverse color is in effect. - -This code isn't super well-supported, and mIRC seems to always treat it as applying the reverse of the default -foreground and background characters, rather than the current fore/background as set by prior mIRC color codes in the -message. - - -### Reset - -`ASCII 0x0F` - -This formatting character resets all formatting. It removes the bold, italics, and underline formatting, and sets the -foreground and background colors back to the default for the client display. The text following this character will use -or display no formatting, until other formatting characters are encountered. - - ---- - - -## Examples - -In this section, the color formatting character `(0x03)` is displayed as <span class="reverse">C</span>, the bold -character `(0x02)` is displayed as <span class="reverse">B</span>, the italics character `(0x1D)` is displayed as -<span class="reverse">I</span>, and the reset character `(0x0F)` is displayed as <span class="reverse">O</span>. - -Each example displays both the raw IRC code sent, and then a formatted version of the output. - -| Code: | <tt>I love <span class="reverse">C</span>3IRC! <span class="reverse">C</span>It is the <span class="reverse">C</span>7best protocol ever!</tt> | -| ------- | - | -| Output: | <tt>I love <span irc_foreground=3>IRC! </span>It is the <span irc_foreground=7>best protocol ever!</span></tt> | - -| Code: | <tt>This is a <span class="reverse">I</span><span class="reverse">C</span>13,9cool <span class="reverse">C</span>message</tt> | -| ------- | - | -| Output: | <tt>This is a <span irc_italic><span irc_foreground=13 irc_background=9>cool </span>message</span></tt> | - -| Code: | <tt>IRC <span class="reverse">B</span>is <span class="reverse">C</span>4,12so <span class="reverse">C</span>great<span class="reverse">O</span>!</tt> | -| ------- | - | -| Output: | <tt>IRC <span irc_bold>is <span irc_foreground=4 irc_background=12>so </span>great</span>!</tt> | - -| Code: | <tt>Rules: Don't spam 5<span class="reverse">C</span>13,8,6<span class="reverse">C</span>,7,8, and especially not <span class="reverse">B</span>9<span class="reverse">B</span><span class="reverse">I</span>!</tt> | -| ------- | - | -| Output: | <tt>Don't spam 5<span irc_foreground=13 irc_background=8>,6</span>,7,8, and especially not <span irc_bold>9</span><span irc_italic>!</span></tt> | \ No newline at end of file diff --git a/docs/irc/index.md b/docs/irc/index.md deleted file mode 100644 index 4bba659ebc1667a0853e5ba4a7e0c1b32100a3f1..0000000000000000000000000000000000000000 --- a/docs/irc/index.md +++ /dev/null @@ -1 +0,0 @@ -# Overview \ No newline at end of file