From 29ea2f46a81c516a08767eafdab9698d5cbd6150 Mon Sep 17 00:00:00 2001 From: Simeon Simeonov Date: Sat, 30 Jun 2018 12:22:35 +0200 Subject: Documentation cleanups. INSTALL -> INSTALL.md, README -> README.md --- README | 122 ----------------------------------------------------------------- 1 file changed, 122 deletions(-) delete mode 100644 README (limited to 'README') diff --git a/README b/README deleted file mode 100644 index f2bf0d5..0000000 --- a/README +++ /dev/null @@ -1,122 +0,0 @@ -Copyright (C) 2014-2018 - Simeon Simeonov -See the end of the file for license conditions. - - -What is BEINC? --------------- - -Blackmore's Enchanced IRC Notification Collection (BEINC) is a free set of -components that aims to provide a complete system for different -on-screen-display notification scenarios. - -The current version of BEINC contains the following components: -beinc_server.py - server used for queueing or providing on-screen-display (OSD) -beinc_poller.py - client used to fetch enqueued messages from beinc_server.py - and provide OSD -beinc_weechat.py - a complete script / client for the Weechat IRC client >=0.4.0 - used to push notification messages to beinc_server.py -beinc_generic_client.py - a simple client used to push notification messages - to beinc_server.py - Its main purpose is to provide a convenient way to - test beinc_server.py (and beinc_poller.py) as well as - to serve as an example for how to develop BEINC-clients -+ documentation and a sample configuration file (beinc_config_sample.json) - - -Why should I use BEINC and what has it done for me lately? ----------------------------------------------------------- - -BEINC is a free-software, licensed under the GPL3. It gives you the freedoms -of using it, studying it and modifying it. - -BEINC is designed to assist you two common scenarios. -As an example we will consider the case of an IRC cliet, although BEINC can be -used by any client that conforms with BEINC's "messaging protocol". - -We have the common situation where a user is accessing an IRC client located on -a different computer (typically: weechat, irssi, etc. running on a remote server) -The IRC client receives a private message (or any event that requires the user's -attention) and the user has to be notified. -No matter which of the two scenarios applies to your needs, you should start by - - setting up a BEINC client similar to beinc_generic_client.py on the server - If you are running weechat >=0.4.0, this version of BEINC comes with - a complete weechat BEINC-client: beinc_weechat.py - Configure the client to send notifications to the beinc_server.py -N.B. Using encryption is important in these days and age. - -Scenario one: -The user's computer can be reached by the server running the IRC client. -If the server (running the IRC client) is able to connect to -a specified TCP port on the user's computer, this is sufficient for BEINC to -directly notify the user. Solution: - - set up the beinc_server.py on the desktop workstation (the computer where the - notification-message should be displayed). Define an unprivileged port for - beinc_server.py to listen on and enable its OSD capabilities - (through pynotify) - -Scenario two: -The user's computer can NOT be reached by the server running the IRC client. -This scenario is typical for users that are working on computers that can not -be reached from outside. -Solution: - - find a server that can be reached by the server running the IRC client. - - set up the beinc_server.py on it. No OSD capabilities are needed (no X11). - Define instance(s) for queueing. Define a queue size - (how many notifications to store) for each of them. - - set up beinc_poller.py on the desktop workstation (the computer where the - notification-message should be displayed). - beinc_poller.py should be able to access the server running beinc_server.py - Polling interval of 5 seconds should be enough for most users. - -Read beinc_config_sample.json.readme for details on how to setup -beinc_server.py and beinc_weechat.py! -Use "-h" command line parameter to display the available options for -beinc_poller.py and beinc_generic_client.py -Each configured beinc_server.py instance has an unique name. -There are 2 operations that can be done on an instance: - - push - a client is sending a notification to the BEINC server. - A push is available for all instances. - - pull - a poller (f.i. beinc_poller.py) is fetching data from the instance-queue. - A pull is available only for instances defined for queueing. - (read beinc_config_sample.json.readme for details!) -Example: -If you defined a beinc_server.py instance with SSL-support, -your URL will be: https://hostname:port - - -Supported systems & requirements --------------------------------- -Any system running the software required for the selected components. -All components tested on: Gentoo GNU/Linux 2014,2015, - Ubuntu GNU/Linux 14.4,14.10, - FreeBSD 10.x - - -Requirements: -All components: Python >= 2.7.9 or Python >= 3.4.* - -beinc_server.py: pynotify >= 0.1 (optional) -beinc_weechat.py: Weechat >= 0.4.0 -beinc_poller.py: pynotify >= 0.1 -beinc_generic_client.py: No additional software required - -Read INSTALL in this very same folder for more details about installing the requirements! - - -License -------- - -This file is part of BEINC. - -BEINC is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see -- cgit v1.3