diff --git a/doc/QuickStart.md b/doc/QuickStart.md index b515f452..f326fbaf 100644 --- a/doc/QuickStart.md +++ b/doc/QuickStart.md @@ -3,33 +3,39 @@ QuickStart This is a work-in-progress rough draft Quick Start guide. This notification will be removed when this guide is mature. -* [QuickStart](#quickstart) - * [Installing](#installing) - * [Prerequisites](#prerequisites) - * [Installing CPAN modules](#installing-cpan-modules) - * [First-time Configuration](#first-time-configuration) - * [Clone data-directory](#clone-data-directory) - * [Edit Registry](#edit-registry) - * [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks) - * [Freenode](#freenode) - * [IRCnet](#ircnet) - * [Other networks](#other-networks) - * [Starting PBot](#starting-pbot) - * [Usage](#usage) - * [Overriding directories](#overriding-directories) - * [Overriding registry](#overriding-registry) - * [Additional Configuration](#additional-configuration) - * [Adding Channels](#adding-channels) - * [Adding Admins](#adding-admins) - * [Loading Plugins](#loading-plugins) +* [Installing](#installing) + * [Installing Perl](#installing-perl) + * [Installing CPAN modules](#installing-cpan-modules) + * [Installing PBot](#installing-pbot) + * [git (recommended)](#git-recommended) + * [Download zip archive](#download-zip-archive) +* [First-time Configuration](#first-time-configuration) + * [Clone data-directory](#clone-data-directory) + * [Edit Registry](#edit-registry) + * [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks) + * [Freenode](#freenode) + * [IRCnet](#ircnet) + * [Other networks](#other-networks) +* [Starting PBot](#starting-pbot) + * [Usage](#usage) + * [Overriding directories](#overriding-directories) + * [Overriding registry](#overriding-registry) +* [Additional Configuration](#additional-configuration) + * [Adding Channels](#adding-channels) + * [Adding Admins](#adding-admins) + * [Loading Plugins](#loading-plugins) Installing ---------- -### Prerequisites +### Installing Perl -#### Installing CPAN modules +PBot uses the [Perl programming language](https://www.perl.org/). Perl is usually +part of a base Linux install. If you do not have Perl installed, please see your +system's documentation to install it. + +### Installing CPAN modules PBot has many features; some of these depend on Perl modules written by others. This list can be found in the `MODULES` file in the root directory of this source. @@ -42,29 +48,60 @@ Some CPAN modules may fail to pass certain tests due to outdated variables. Despite these test failures, their core functionality should still work as expected. +### Installing PBot + +#### git (recommended) + +The recommended way to install PBot is via `git`. This will allow you easily update to +the latest version of PBot via the `git pull` command. Also, if you become interested in +contributing improvements to PBot, you will be able to submit them via `git`. + +The command to install with `git` is: + + $ git clone https://github.com/pragma-/pbot.git + +#### Download zip archive + +Alternatively, you may [download a ZIP archive](https://github.com/pragma-/pbot/archive/master.zip). + First-time Configuration ------------------------ +After git-cloning (or unpacking the ZIP archive) you should have a directory named +`pbot/` (or `pbot-master/`). It should contain at least these directories and files: + +Name | Description +--- | --- +`PBot/` | PBot source tree +`Plugins/` | Dynamically loadable internal plugins +`modules/` | External command-line executables invokable by PBot commands +`data/` | Default data-directory +`doc/` | Helpful documentation +`pbot` | executable used to launch PBot + +You may create symbolic-links to the `pbot` executable in `$HOME/bin/` or even +in `/usr/local/bin/`. + ### Clone data-directory -PBot uses a data-directory to store all its configuration settings and data. It -is **_strongly_** recommended to clone the default data-directory for each PBot -connection. +PBot uses a data-directory to store all its configuration settings and data. You must +clone this data-directory for each instance of PBot you want to run. Here we clone the data-directory for two PBot instances, naming them after the IRC network they will connect to: - cp -r data freenode - cp -r data ircnet + $ cd pbot (or pbot-master) + $ cp -r data freenode + $ cp -r data ircnet Alternatively, you could name it after your bot's nickname: - cp -r data coolbot + $ cp -r data coolbot ### Edit Registry PBot configuration is stored in a registry of key/value pairs grouped by sections. -See https://github.com/pragma-/pbot/blob/master/doc/Registry.md for more details. +See the [Registry documentation](https://github.com/pragma-/pbot/blob/master/doc/Registry.md) for more details. Now you may edit the `registry` file in your data-directory to configure PBot settings. Alternatively, you may [override the registry entries via the command-line](#overriding-registry). @@ -80,7 +117,7 @@ irc.server | IRC server address to connect. | irc.freenode.net irc.port | IRC server port. | 6667 general.trigger | Bot trigger. Can be a character class containing multiple trigger characters. Can be overridden per-channel. | [!] -For a more comprehensive list see https://github.com/pragma-/pbot/blob/master/doc/Registry.md#list-of-recognized-registry-items. +For a more comprehensive list see [this table](https://github.com/pragma-/pbot/blob/master/doc/Registry.md#list-of-recognized-registry-items). #### Recommended settings for IRC Networks ##### Freenode @@ -115,7 +152,7 @@ general.op_command | Command to send to `general.op_nick` to request channel OP ##### Other networks Other networks are untested. They should be very similiar to either Freenode or IRCnet, and so one or both of those -recommended settings should suffice. If you have any issues, please report them at https://github.com/pragma-/pbot/issues +recommended settings should suffice. If you have any issues, please [report them here](https://github.com/pragma-/pbot/issues) or in the `#pbot2` channel on the Freenode network. Starting PBot