diff options
authoropal hart <opal@wowana.me>2018-11-09 11:41:10 +0000
committeropal hart <opal@wowana.me>2018-11-09 11:41:10 +0000
commitd24eedc982425713695249ee5bbd04b1db88e9cb (patch)
parent791ed3385e645ec555f19dbfe551da042a95ac41 (diff)
doc: README and other documentation
4 files changed, 214 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..04ce838
--- /dev/null
+++ b/README
@@ -0,0 +1,16 @@
+ `-,==;
+ `-.==`/
+ ,/ ,/
+ .-========-__._-=''```¯¯¯¯¯`'.
+ ¯¯¯¯¯¯¯¯`'=.,^~__,,_====-. `.
+ '===:'¯ . .' ; |
+ ¯'=,' -' |
+ ¯'=, /
+ A c h l y s ) (
+ | -=.'._,
+ A powerful commandline \ (x /¯
+ multi-protocol chat client '---'
+What's special about it? See <./doc/Introduction>
+How do I build it? See <./doc/Building>
+How can I help? See <./doc/Contributing>
diff --git a/doc/Building b/doc/Building
new file mode 100644
index 0000000..285ca9e
--- /dev/null
+++ b/doc/Building
@@ -0,0 +1,29 @@
+Build prerequisites:
+The build process is fairly straightforward. All you need is a POSIX-
+compatible system, a C99 preprocesser/compiler/linker, and a make
+utility. You will also need some knowledge of the tools you are using,
+in order to get the most out of achlys.
+If there are any issues building on your POSIX-compatible system, please
+see <./doc/Contributing> for information on how to report a bug and/or
+submit a patch. I will take all compatibility issues seriously: there
+are very few platform-specific functions in achlys, and I do my best to
+provide compliant alternatives for users on other platforms.
+General building:
+Basically, just run `./configure && make all` and then, if there are no
+issues, an executable <./achlys> will be produced. There is no `make
+install` for now.
+Advanced building:
+Additional compile-time configuration is possible; run `./configure
+--help` for a list of options. You may also edit <./buildconf/custom.mk>
+to include any local rules and options that you wouldn't be able to set
+Changing code might require use of the makedepend(1) utility. Please
+obtain this for your system if you wish to modify the code, and run
+`make depend` to generate a header dependency file.
diff --git a/doc/Contributing b/doc/Contributing
new file mode 100644
index 0000000..ecee3bd
--- /dev/null
+++ b/doc/Contributing
@@ -0,0 +1,74 @@
+I will set up a mailing list for achlys development, but for now please
+E-mail <achlys@wowana.me> or join irc.volatile.bz+6697 #achlys to
+All C code shall be C99-valid.
+Makefiles shall be cross-platform (often, this means conforming to
+Shell scripts shall be usable in POSIX sh, with #!/bin/sh shebang line.
+Keep all non-development matters to yourself. This project is a neutral
+space, and all appropriate action will be taken for it to remain as
+such. All contributions are to be judged by their developmental value
+and by nothing else.
+Code style:
+Keep lines short when it makes sense (72-80 characters is a good rule).
+Use tabs to indent, spaces to format.
+Use the macros supplied in <./src/core/common.h> rather than the
+language-provided equivalents, such as ax_malloc and ax_free. Even if
+they are equivalent in function now, the implementation may change in
+the future, and this ensures that code is easy to change.
+Because ax_free() is one of these macros, use-after-free should become
+impossible and lead to a null dereference.
+Do not assert() that a pointer is non-null. POSIX-conformant systems
+treat NULL specially and will fail sanely. Assertions can and should be
+used for any other difficult code that cannot easily be caught.
+Keep functions, variables, and struct definitions to the smallest scope
+that you need.
+Read the code for anything you're unsure about. Following is a sample
+code with proper formatting, to give you a general idea of how your code
+should look.
+/* Use ANSI C comments only.
+ * Code should be self-documenting and describe the "how".
+ * Comments should be reserved to describe the "why".
+ */
+void function (const char* foo, unsigned bar,
+ struct baz quux)
+ /* Place declarations at top of scope, one per line */
+ int x;
+ int y;
+ int z = 123;
+ (void) quux;
+ /* Braces on same line, no "cuddled else". Braces may be omitted
+ * when unnecessary, but when in doubt, include them.
+ */
+ if (bar < z) {
+ y = 1;
+ ++z;
+ }
+ else if (bar > z) {
+ y = 2;
+ --z;
+ }
+ else while (( x = do_something(bar) ))
+ do_something_else(foo);
+ switch (y) {
+ case 1:
+ case 2:
+ blah(z);
+ break;
+ default:
+ blah(x);
+ break;
+ }
diff --git a/doc/Introduction b/doc/Introduction
new file mode 100644
index 0000000..ed7889b
--- /dev/null
+++ b/doc/Introduction
@@ -0,0 +1,95 @@
+vi:set tw=72 noai nosi:
+What is achlys?
+ It's a chat program with powerful design goals:
+ - Modularity. The core code only has enough to load modules, access
+ configuration, run the event loop, call hooks, and parse commands.
+ The I/O and chat protocols are handled in loadable modules,
+ allowing users to use only the functionality they need.
+ - Scriptability. Since the core handles command parsing and much of
+ achlys' functionality is built off scripts, the language needs to
+ be powerful, intuitive, and domain-specific. This is a chat
+ program, not a general-purpose scripting environment, so it makes
+ sense to incorporate IRC-style commands and extend them a bit to
+ be more natural and powerful to use.
+ - Power usage. Achlys is designed ground-up to accomodate my
+ messaging needs. After years of using various IRC and IM clients,
+ I have realised they are all mediocre for how much time I spend in
+ these programs. I use them to talk to friends and keep up on
+ software development. Why can't my chat client be as natural and
+ as powerful as my text editor? Why do I need to use a different
+ program for each account? Why do I need compatibility shims such
+ as ZNC and bitlbee when it could be built-in to my client?
+What's it look like?
+ The main client UI is line-based like a shell (or like the IRC
+clients ii/sic, or eggdrop partyline, et cetera) and as such it is
+entirely command-based, not focused on windowed UI or a selection of key
+bindings. This will likely catch people off guard who are used to
+windowed navigation, but this was a conscious design choice and I
+believe abandoning a traditional interface allows for greater
+flexibility. Chat is predominantly text-based, so the interface is also
+best represented as text.
+ I normally idle in a lot of IRC channels (upwards of 100) and only
+check on them when I want to talk about a specific subject or when I am
+mentioned. Throw a few XMPP chats with friends and a couple Discord
+servers on top of that, and I have a lot to manage. I only want messages
+I'm interested in, though, and I don't want to have to shuffle between
+windows every time I see new activity. The client should do this for me.
+Because of this, having everything in one window makes sense. And in
+that window I can filter using rules such as:
+ * messages mentioning me: they're about me so they must be important,
+ * messages mentioning a particular subject or pattern of interest,
+ * private messages from my friends: I always want to see those,
+ * a few "favourite" channels that I always participate in: usually
+ they're low-traffic enough where I can comfortably follow the
+ conversation,
+ * some other key events such as if I get banned from a channel.
+We all deal with spam, too. On top of those basic filters, I can add
+ * if I receive too many mentions, temporarily condense them and just
+ tell me how many lines I'm missing,
+ * I can block all unknown PMs -- think umode +g on IRC but better,
+ because I can easily view the PMs I missed if I later decide to
+ accept the user,
+ * if a channel gets too noisy, or if I'm just tired of talking
+ somewhere, I can mute that for a while as well.
+For people used to windowed layout (or whenever you want to focus on one
+specific chat and tune everything else out), you can also filter
+messages based on your active channel or query. That way you can `/go
+#channel` just like you would in other clients and it wouldn't feel too
+different from what you're used to. Due to the modularity of achlys,
+anyone is also able to write a GUI, ncurses, mobile-app, or even a
+filesocket/scripting interface and interact with achlys in a more
+comfortable manner.
+Isn't this a step back from windowed clients still?
+ Achlys aims to support modern standards: 256-colour support, OTR,
+OMEMO, IRCv3, TLS, SASL, and whatever else I can think of adding (or
+whatever you add for yourself). I believe windowed clients are a step
+back from peak efficiency, and it took me years of dealing with windows
+and buffers to figure this out. Also, you will benefit from smart
+tab-completion, partial command completion, and other handy time-saving
+ Other "power" features (mostly for IRC) include advanced scripting
+support, support for multiple connections per network (useful to replace
+Wraith to maintain your channel, or to bypass flood / channel membership
+limitations, or whatever suits your fancy), support for proxies and
+proxy lists, and inline scripting with consistent syntax (in fact, every
+message you send is interpreted through this scripting).
+I want to switch. What's the same and what's different than what I'm used to?
+ First of all, get accustomed to the `/help` command. Run it before
+you do anything else and you'll already get a feel for things.
+ If you've had enough of achlys, type `/exit`. This will not ask you
+for confirmation and will only shut down the client, not the daemon (by
+default). `/quit` is an entirely different command, so don't confuse
+the two.
+ Have more questions after that? Join us:
+/irc irc.volatile.bz+6697
+/join #achlys
+You may also contribute your time by reporting or fixing bugs on the
+mailing list; see <./doc/Contributing> for more information. Feature
+requests should be accompanied by patches if you want them considered;
+patches are also preferred for bug fixes but I will take all bug reports
+into account.