doc: add WIP QuickStart.md *rough* draft for preview

doc/QuickStart.md

@@ -0,0 +1,132 @@
+QuickStart
+==========
+PBot is an IRC bot written in Perl. This is a work-in-progress rough draft Quick Start guide.
+This notification will be removed when this guide is mature.
+
+
+<!-- md-toc-begin -->
+* [QuickStart](#quickstart)
+  * [Installing](#installing)
+    * [Prerequisites](#prerequisites)
+      * [Installing CPAN modules](#installing-cpan-modules)
+        * [Caveats](#caveats)
+          * [re::engine::RE2](#reenginere2)
+  * [First-time Configuration](#first-time-configuration)
+    * [Clone data-directory](#clone-data-directory)
+    * [Edit Registry](#edit-registry)
+      * [Notable settings](#notable-settings)
+      * [Recommended settings for IRC Networks](#recommended-settings-for-irc-networks)
+        * [Freenode](#freenode)
+        * [IRCnet](#ircnet)
+        * [Other networks](#other-networks)
+    * [Adding Channels](#adding-channels)
+    * [Adding Admins](#adding-admins)
+    * [Loading Plugins](#loading-plugins)
+<!-- md-toc-end -->
+
+Installing
+----------
+
+### Prerequisites
+
+#### 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.
+
+The modules may be installed with a simple command:
+
+    cpan -f -i $(cat MODULES)
+
+##### Caveats
+
+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.
+
+###### re::engine::RE2
+There have been reports that this module may not install. TODO: workaround.
+
+First-time Configuration
+------------------------
+
+### 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.
+
+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
+
+Alternatively, you could name it after your bot's nickname:
+
+    cp -r data coolbot
+
+You get the idea.
+
+### Edit Registry
+
+Now you may edit the `registry` file in your data-directories to configure PBot
+settings.
+
+#### Notable settings
+
+Some settings you may be interested in configuring:
+
+Registry key | Description | Default value
+--- | --- | ---:
+irc.botnick | IRC nickname. This is the name people see when you talk. | _undefined_
+irc.username | IRC username. This is the `USER` field of your hostmask. | pbot3
+irc.ircname | IRC gecos/realname. This is the `general information` or `real-name` field, as seen in `WHOIS`. | https://github.com/pragma-/pbot
+irc.ircserver | IRC server to connect | irc.freenode.net
+irc.port | IRC server port | 6667
+irc.identify_password | Password to use to identify to NickServ/service bot. | _undefined_
+irc.randomize_nick | Randomize IRC nickname when connecting to server. PBot will change to irc.botnick when connected or logged-in. | 0
+general.trigger | Bot trigger | [!]
+general.autojoin_wait_for_nickserv | Wait for NickServ login before auto-joining channels. | 0
+general.identify_nick | Who to /msg for login/identify/authentication. Defaults to NickServ, can be overridden to a custom bot. | NickServ
+general.identify_command | Command to send to `general.identify_nick` to login. | identify $nick $password
+general.op_nick | Who to /msg to request channel OP status. Defaults to ChanServ, can be overridden to a custom bot. | ChanServ
+general.op_command | Command to send to `general.op_nick` to request channel OP status. | op $channel
+googlesearch.api_key | API key for Google Custom Search. | _undefined_
+googlesearch.context | Google Custom Search context key. | _undefined_
+
+#### Recommended settings for IRC Networks
+##### Freenode
+
+The default settings are tailored for the Freenode IRC network. It is strongly recommended that
+you register an account with its NickServ service and to request a hostmask cloak. It is strongly
+recommended to register your channels with its ChanServ service. These services will protect your
+nick, IP address and channels.
+
+Once you register your botnick with NickServ, it is recommended to set `irc.randomize_nick` to `1`.
+This will cause PBot to connect to the network with a randomized nickname, which will prevent users
+from watching for your connection to attempt to capture your IP address.
+
+Then set `irc.autojoin_wait_for_nickserv` to `1`. This will cause PBot to wait until logged into NickServ
+before attempting to auto-join your channels, to ensure your NickServ host cloak is applied beforehand.
+
+##### IRCnet
+
+IRCnet is one of the oldest IRC networks still running. It has no Services like NickServ and ChanServ.
+Instead, its nicknames and channels are protected by custom bots. You may configure the
+`general.identify_nick`, `general.identify_command`, `general.op_nick` and `general.op_command` settings
+to point at custom bots and commands to login/request OP.
+
+##### Other networks
+
+Other networks are untested. They should be very similiar to either Freenode or IRCnet, and so one of those
+recommended settings should work. If you have any issues, please report them at https://github.com/pragma-/pbot/issues.
+
+### Adding Channels
+
+### Adding Admins
+
+### Loading Plugins
+
+
+