Skip to content

Commit dd6d996

Browse files
authored
README improvements (#47)
* Update for SEO * Update README.md * add ANSI example * Update README.md * Update README.md * Update README.md * Update README.md * Add files via upload * add new screenshot image (cropped) * add more usage information
1 parent 7fb34f6 commit dd6d996

File tree

2 files changed

+73
-45
lines changed

2 files changed

+73
-45
lines changed

.github/example4.png

430 KB
Loading

README.md

Lines changed: 73 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,21 @@
44
Author: mcpcpc
55
-->
66

7-
<h3 align="center"><img src="https://raw.githubusercontent.com/mcpcpc/kirc/master/.github/kirc.png" alt="logo" height="170px"></h3>
7+
<h3 align="center">
8+
<img src="https://raw.githubusercontent.com/mcpcpc/kirc/master/.github/kirc.png" alt="kirc" height="170px">
9+
</h3>
10+
811
<p align="center">KISS for IRC, a tiny IRC client written in POSIX C99.</p>
12+
913
<p align="center">
10-
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
11-
<a href="https://github.com/mcpcpc/kirc/releases"><img src="https://img.shields.io/github/v/release/mcpcpc/kirc.svg"></a>
12-
<a href="https://repology.org/metapackage/kirc"><img src="https://repology.org/badge/tiny-repos/kirc.svg" alt="Packaging status"></a>
13-
<a href="https://www.codacy.com/manual/mcpcpc/kirc/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=mcpcpc/kirc&amp;utm_campaign=Badge_Grade"><img src="https://app.codacy.com/project/badge/Grade/5616c0ed4b2f4209826038dbc270dbf5" alt="Codacy status"></a>
14+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
15+
<a href="https://github.com/mcpcpc/kirc/releases"><img src="https://img.shields.io/github/v/release/mcpcpc/kirc.svg"></a>
16+
<a href="https://repology.org/metapackage/kirc"><img src="https://repology.org/badge/tiny-repos/kirc.svg" alt="Packaging status"></a>
17+
<a href="https://www.codacy.com/manual/mcpcpc/kirc/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=mcpcpc/kirc&amp;utm_campaign=Badge_Grade"><img src="https://app.codacy.com/project/badge/Grade/5616c0ed4b2f4209826038dbc270dbf5" alt="Codacy status"></a>
18+
</p>
19+
20+
<p align="center">
21+
<img src=".github/example4.png" width="550">
1422
</p>
1523

1624
## Features
@@ -19,7 +27,7 @@
1927
* No dependencies other than a [C99 compiler](https://en.wikipedia.org/wiki/C99).
2028
* Native [SASL PLAIN and EXTERNAL](https://tools.ietf.org/html/rfc4422) authentication support.
2129
* [TLS/SSL](https://en.m.wikipedia.org/wiki/Transport_Layer_Security) protocol capable (via external TLS utilities).
22-
* Chat history logging.
30+
* Full chat history logging.
2331
* Multi-channel joining at server connection.
2432
* Simple shortcut commands and full support for all IRC commands in the [RFC 2812](https://tools.ietf.org/html/rfc2812) standard:
2533

@@ -31,15 +39,9 @@
3139
/? Print current message channel.
3240
```
3341

34-
* Color scheme definition via [ANSI 8-bit colors](https://en.wikipedia.org/wiki/ANSI_escape_code). Therefore, one could theoretically achieve uniform color definition across all shell applications and tools.
35-
36-
## Screenshots
37-
38-
![Screenshot 1](/.github/example.png)
42+
* Color scheme definition via [ANSI 8-bit colors](https://en.wikipedia.org/wiki/ANSI_escape_code), allowing for uniform color definition across all shell applications.
3943

40-
![Screenshot 1](/.github/example2.png)
41-
42-
## Installation
44+
## Installation & Usage
4345

4446
Building and installing on **KISS Linux** using the Community repository:
4547

@@ -65,37 +67,26 @@ make
6567
make install
6668
```
6769

68-
## Usage
70+
### Usage
71+
72+
Consult `man kirc` for a full list and explanation of available `kirc` arguments.
6973

7074
```shell
71-
usage: kirc [-s hostname] [-p port] [-c channel] [-n nick] [-r real name] [-u username] [-k password] [-x init command] [-w columns] [-W columns] [-o path] [-e|v|V]
72-
-s server address (default: 'irc.freenode.org')
73-
-p server port (default: '6667')
74-
-c channel name(s), delimited by a "," or "|" character (default: 'kirc')
75-
-n nickname (required)
76-
-u server username (optional)
77-
-k server password (optional)
78-
-a PLAIN SASL authentication token (optional, specified with nick)
79-
-e EXTERNAL SASL authentication (optional)
80-
-r real name (optional)
81-
-v version information
82-
-V verbose output (e.g. raw stream)
83-
-o output path to log irc stream
84-
-x send command to irc server after inital connection
85-
-w maximum width of the printed left column (default: '20')
86-
-W maximum width of the entire printed stream (default '80')
75+
kirc [-s hostname] [-p port] [-c channels] [-n nickname] [-r realname] [-u username] [-k password] [-x command] [-w nick_width] [-W max_width] [-o logfile] [-e|v|V]
8776
```
8877

8978
## Transport Layer Security (TLS) Support
9079

91-
There is no native TLS/SSL support. Instead, users can achieve this functionality by using third-party utilities (e.g. stunnel, socat, ghosttunnel, etc).
80+
There is no native TLS/SSL support. Instead, users can achieve this functionality by using third-party utilities (e.g. stunnel, [socat](https://linux.die.net/man/1/socat), ghosttunnel, etc).
81+
82+
### Example using `socat`
9283

93-
* [socat](https://linux.die.net/man/1/socat) example (remember to replace items enclosed with `<>`):
84+
Remember to replace items enclosed with `<>`.
9485

95-
```shell
96-
socat tcp-listen:6667,reuseaddr,fork,bind=127.0.0.1 ssl:<irc-server>:6697
97-
kirc -s 127.0.0.1 -c 'channel' -n 'name' -r 'realname'
98-
```
86+
```shell
87+
socat tcp-listen:6667,reuseaddr,fork,bind=127.0.0.1 ssl:<irc-server>:6697
88+
kirc -s 127.0.0.1 -c 'channel' -n 'name' -r 'realname'
89+
```
9990

10091
## SASL PLAIN Authentication
10192

@@ -115,17 +106,54 @@ $ kirc -n jilles -a amlsbGVzAGppbGxlcwBzZXNhbWU=
115106

116107
## SASL EXTERNAL Authentication
117108

118-
Similar to `SASL PLAIN`, the `SASL EXTERNAL` mechanism allows us to authenticate using credentials by external means. An example where this might be required is when trying to connect to an IRC host through [Tor](https://www.torproject.org/). To do so, we can using third-party utilities (e.g. stunnel, socat, ghosttunnel, etc).
109+
Similar to `SASL PLAIN`, the `SASL EXTERNAL` mechanism allows us to authenticate using credentials by external means. An example where this might be required is when trying to connect to an IRC host through [Tor](https://www.torproject.org/). To do so, we can using third-party utilities (e.g. stunnel, [socat](https://linux.die.net/man/1/socat), ghosttunnel, etc).
110+
111+
### Example using `socat`
119112

120-
* [socat](https://linux.die.net/man/1/socat) example (remember to replace items enclosed with `<>`):
113+
Remember to replace items enclosed with `<>`.
121114

122-
```shell
123-
socat TCP4-LISTEN:1110,fork,bind=0,reuseaddr SOCKS4A:127.0.0.1:<onion_address.onion>:<onion_port>,socksport=9050
124-
socat TCP4-LISTEN:1111,fork,bind=0,reuseaddr 'OPENSSL:127.0.0.1:1110,verify=0,cert=<path_to_pem>'
125-
kirc -e -s 127.0.0.1 -p 1111 -n <nick> -x 'wait 5000'
126-
```
115+
```shell
116+
socat TCP4-LISTEN:1110,fork,bind=0,reuseaddr SOCKS4A:127.0.0.1:<onion_address.onion>:<onion_port>,socksport=9050
117+
socat TCP4-LISTEN:1111,fork,bind=0,reuseaddr 'OPENSSL:127.0.0.1:1110,verify=0,cert=<path_to_pem>'
118+
kirc -e -s 127.0.0.1 -p 1111 -n <nick> -x 'wait 5000'
119+
```
120+
121+
## Color Scheme Definition
122+
123+
Applying a new color scheme is easy! One of the quickest ways is to use an application, such as [kfc](https://github.com/mcpcpc/kfc), to apply pre-made color palettes. Alternatively, you can manually apply escape sequences to change the default terminal colors.
124+
125+
### Example using `kfc`
126+
127+
```shell
128+
kfc -s gruvbox
129+
```
130+
131+
### Example using ANSI escape sequences
132+
133+
```shell
134+
printf -e "\033]4;<color_number>;#<hex_color_code>"
135+
136+
# Replace <hex_color_code> with the desired Hex code (e.g. #FFFFFF is white).
137+
# Replace <color_number> with the one of the numbers below:
138+
# 0 - Regular Black
139+
# 1 - Regular Red
140+
# 2 - Regular Green
141+
# 3 - Regular Yellow
142+
# 4 - Regular Blue
143+
# 5 - Regular Magenta
144+
# 6 - Regular Cyan
145+
# 7 - Regular White
146+
# 8 - Bright Black
147+
# 9 - Bright Red
148+
# 10 - Bright Green
149+
# 11 - Bright Yellow
150+
# 12 - Bright Blue
151+
# 13 - Bright Magenta
152+
# 14 - Bright Cyan
153+
# 15 - Bright White
154+
```
127155

128156
## Contact
129157

130-
For any further questions or concerns, feel free to reach out to me on `#kirc`
158+
For any further questions or concerns, feel free to reach out to me, [mcpcpc](https://github.com/mcpcpc), on `#kirc`
131159
or `#kisslinux` channels of the _irc.freenode.org_ server.

0 commit comments

Comments
 (0)