From dd6d9963b4ff229dae5875be6811b0abb2d68a2e Mon Sep 17 00:00:00 2001 From: Michael Czigler <37268479+mcpcpc@users.noreply.github.com> Date: Wed, 30 Sep 2020 11:38:06 -0400 Subject: 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 --- .github/example4.png | Bin 0 -> 439810 bytes README.md | 118 +++++++++++++++++++++++++++++++-------------------- 2 files changed, 73 insertions(+), 45 deletions(-) create mode 100644 .github/example4.png diff --git a/.github/example4.png b/.github/example4.png new file mode 100644 index 0000000..c4b8a43 Binary files /dev/null and b/.github/example4.png differ diff --git a/README.md b/README.md index f94ebeb..9e45fc7 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,21 @@ Author: mcpcpc --> -

logo

+

+ kirc +

+

KISS for IRC, a tiny IRC client written in POSIX C99.

+

- - -Packaging status -Codacy status + + + Packaging status + Codacy status +

+ +

+

## Features @@ -19,7 +27,7 @@ * No dependencies other than a [C99 compiler](https://en.wikipedia.org/wiki/C99). * Native [SASL PLAIN and EXTERNAL](https://tools.ietf.org/html/rfc4422) authentication support. * [TLS/SSL](https://en.m.wikipedia.org/wiki/Transport_Layer_Security) protocol capable (via external TLS utilities). -* Chat history logging. +* Full chat history logging. * Multi-channel joining at server connection. * Simple shortcut commands and full support for all IRC commands in the [RFC 2812](https://tools.ietf.org/html/rfc2812) standard: @@ -31,15 +39,9 @@ /? Print current message channel. ``` -* 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. - -## Screenshots - -![Screenshot 1](/.github/example.png) +* 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. -![Screenshot 1](/.github/example2.png) - -## Installation +## Installation & Usage Building and installing on **KISS Linux** using the Community repository: @@ -65,37 +67,26 @@ make make install ``` -## Usage +### Usage + +Consult `man kirc` for a full list and explanation of available `kirc` arguments. ```shell -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] --s server address (default: 'irc.freenode.org') --p server port (default: '6667') --c channel name(s), delimited by a "," or "|" character (default: 'kirc') --n nickname (required) --u server username (optional) --k server password (optional) --a PLAIN SASL authentication token (optional, specified with nick) --e EXTERNAL SASL authentication (optional) --r real name (optional) --v version information --V verbose output (e.g. raw stream) --o output path to log irc stream --x send command to irc server after inital connection --w maximum width of the printed left column (default: '20') --W maximum width of the entire printed stream (default '80') +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] ``` ## Transport Layer Security (TLS) Support -There is no native TLS/SSL support. Instead, users can achieve this functionality by using third-party utilities (e.g. stunnel, socat, ghosttunnel, etc). +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). + +### Example using `socat` -* [socat](https://linux.die.net/man/1/socat) example (remember to replace items enclosed with `<>`): +Remember to replace items enclosed with `<>`. - ```shell - socat tcp-listen:6667,reuseaddr,fork,bind=127.0.0.1 ssl::6697 - kirc -s 127.0.0.1 -c 'channel' -n 'name' -r 'realname' - ``` +```shell +socat tcp-listen:6667,reuseaddr,fork,bind=127.0.0.1 ssl::6697 +kirc -s 127.0.0.1 -c 'channel' -n 'name' -r 'realname' +``` ## SASL PLAIN Authentication @@ -115,17 +106,54 @@ $ kirc -n jilles -a amlsbGVzAGppbGxlcwBzZXNhbWU= ## SASL EXTERNAL Authentication -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). +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). + +### Example using `socat` -* [socat](https://linux.die.net/man/1/socat) example (remember to replace items enclosed with `<>`): +Remember to replace items enclosed with `<>`. - ```shell - socat TCP4-LISTEN:1110,fork,bind=0,reuseaddr SOCKS4A:127.0.0.1::,socksport=9050 - socat TCP4-LISTEN:1111,fork,bind=0,reuseaddr 'OPENSSL:127.0.0.1:1110,verify=0,cert=' - kirc -e -s 127.0.0.1 -p 1111 -n -x 'wait 5000' - ``` +```shell +socat TCP4-LISTEN:1110,fork,bind=0,reuseaddr SOCKS4A:127.0.0.1::,socksport=9050 +socat TCP4-LISTEN:1111,fork,bind=0,reuseaddr 'OPENSSL:127.0.0.1:1110,verify=0,cert=' +kirc -e -s 127.0.0.1 -p 1111 -n -x 'wait 5000' +``` + +## Color Scheme Definition + +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. + +### Example using `kfc` + +```shell +kfc -s gruvbox +``` + +### Example using ANSI escape sequences + +```shell +printf -e "\033]4;;#" + +# Replace with the desired Hex code (e.g. #FFFFFF is white). +# Replace with the one of the numbers below: +# 0 - Regular Black +# 1 - Regular Red +# 2 - Regular Green +# 3 - Regular Yellow +# 4 - Regular Blue +# 5 - Regular Magenta +# 6 - Regular Cyan +# 7 - Regular White +# 8 - Bright Black +# 9 - Bright Red +# 10 - Bright Green +# 11 - Bright Yellow +# 12 - Bright Blue +# 13 - Bright Magenta +# 14 - Bright Cyan +# 15 - Bright White +``` ## Contact -For any further questions or concerns, feel free to reach out to me on `#kirc` +For any further questions or concerns, feel free to reach out to me, [mcpcpc](https://github.com/mcpcpc), on `#kirc` or `#kisslinux` channels of the _irc.freenode.org_ server. -- cgit v1.2.3