Update some documentation

doc/Admin.md

@@ -122,18 +122,19 @@ This is a list of recognized metadata keys for user accounts.
 
 Name | Description
 --- | ---
-`hostmasks` | A comma-separated list of hostmasks this user is recognized by.
-`channels` | A comma-separated list of channels this user belongs to.
-`password` | The password for the user account.
-`loggedin` | Whether the user is logged in or not.
-`stayloggedin` | Do not log the user out when they part/quit.
 `autologin` | Automatically log the user in when they join the channel. *Note: make sure the user account's hostmask wildcards are as restrictive as possible.*
 `autoop` | Give the user `operator` status when they join the channel. *Note: make sure the user account's hostmask wildcards are as restrictive as possible.*
 `autovoice` | Give the user `voiced` status when they join the channel. *Note: make sure the user account's hostmask wildcards are as restrictive as possible.*
-`location` | Sets your location for using the [`weather`](Commands.md#weather) command without any arguments.
-`timezone` | Sets your timezone for using the [`date`](Commands.md#date) command without any arguments.
-`notyposub` | Disallows `s///` typo substitutions.
 [capabilities](#user-capabilities-list) | [User-capabilities](#user-capabilities) are managed as user metadata.
+`channels` | A comma-separated list of channels this user belongs to.
+`hostmasks` | A comma-separated list of hostmasks this user is recognized by.
+`location` | Sets your location for using the [`weather`](Commands.md#weather) command without any arguments.
+`loggedin` | Whether the user is logged in or not.
+`notyposub` | Disallows `s///` typo substitutions.
+`password` | The password for the user account.
+`stayloggedin` | Do not log the user out when they part/quit.
+`timezone` | Sets your timezone for using the [`date`](Commands.md#date) command without any arguments.
+`units` | Sets the unit for Wolfram\|Alpha answers (`imperial` or `metric`)
 
 ### Listing users
 To list user accounts, use the `users` command. This is not an admin command, but

doc/FAQ.md

@@ -7,23 +7,24 @@ This is a work in progress. More questions coming soon!
   * [How do I make PBot remember my `weather` location?](#how-do-i-make-pbot-remember-my-weather-location)
   * [How do I change the bot trigger?](#how-do-i-change-the-bot-trigger)
   * [How do I whitelist a user?](#how-do-i-whitelist-a-user)
+  * [How do I change how the bot outputs multi-line messages?](#how-do-i-change-how-the-bot-outputs-multi-line-messages)
 <!-- md-toc-end -->
 
 ### How do I change my password?
 Use the [`my`](Commands.md#my) command to set the `password` user metadata for your
-user account.
+user account. Your hostmask must match the user account.
 
     my password <your password>
 
 ### How do I make PBot remember my `date` timezone?
 Use the [`my`](Commands.md#my) command to set the `timezone` user metadata for your
-user account.
+user account. Your hostmask must match the user account.
 
     my timezone <your timezone>
 
 ### How do I make PBot remember my `weather` location?
 Use the [`my`](Commands.md#my) command to set the `location` user metadata for your
-user account.
+user account. Your hostmask must match the user account.
 
     my location <your location>
 
@@ -64,3 +65,28 @@ If the user already exists, use the [`userset`](Admin.md#userset) command to
 grant them the `is-whitelisted` capability.
 
 Usage: `userset <username> is-whitelisted 1`
+
+### How do I change how the bot outputs multi-line messages?
+When output from a command contains newlines, PBot will convert the newlines
+to spaces and output it as one message.
+
+If you prefer to output each line instead, you can control this behavior with
+the `general.preserve_newlines` and `general.max_newlines` registry entries. To
+set this behavior for specific channels, replace `general` with the `#channel`.
+
+For example:
+
+    <pragma-> !sh printf "a\nb\nc\nd\ne\n"
+       <PBot> a b c d e
+
+    <pragma-> !regset general.preserve_newlines 1
+       <PBot> general.preserve_newlines set to 1
+
+    <pragma-> !regset general.max_newlines 4
+       <PBot> general.preserve_newlines set to 4
+
+    <pragma-> !sh printf "a\nb\nc\nd\ne\n"
+       <PBot> a
+       <PBot> b
+       <PBot> c
+       <PBot> And that's all I have to say about that. See https://0x0.st/-Okb.txt for full text.

doc/QuickStart.md

@@ -56,24 +56,29 @@ your home directory using, .e.g., [perlbrew](https://metacpan.org/pod/perlbrew),
 ### Installing PBot
 
 #### git (recommended)
-The recommended way to install PBot is with `git`.  This will allow you easily update to
+The recommended way to install PBot is with `git`.  This will allow you to easily update to
 the latest version of PBot via the git update process by issuing the `git pull` command.
 Also, if you become interested in contributing improvements to PBot, you will be able to
 submit them through `git`.
 
 The command to install with `git` is:
 
-    $ git clone https://github.com/pragma-/pbot.git
+    $ git clone --recursive https://github.com/pragma-/pbot.git
 
 #### Download zip archive
 Alternatively, you may [download a ZIP archive](https://github.com/pragma-/pbot/archive/master.zip).
 
+If you want to use the [Plang](https://github.com/pragma-/Plang) scripting language within PBot, you'll
+need to [download the Plang ZIP archive](https://github.com/pragma-/Plang/archive/master.zip) as well.
+Extract it into `pbot/Plang` after you extract the PBot ZIP archive into `pbot`.
+
 ## Initial Setup
-After git-cloning (or unpacking the ZIP archive) you should have a directory named
+After git-cloning (or unpacking the ZIP archives) you should have a directory named
 `pbot/` (or `pbot-master/`). It should contain at least these directories and files:
 
 Name | Description
 --- | ---
+[`Plang/`](../Plang) | Plang scripting language
 [`lib/`](../lib) | PBot source tree
 [`script/`](../script) | PBot executables (e.g., [`script/pbot`](../script/pbot))
 [`modules/`](../modules) | External command-line executables invokable as PBot commands
@@ -155,7 +160,8 @@ You may then choose to install the missing CPAN modules on a feature-by-feature
 where `...` is an optional PBot feature listed in PBot's [`cpanfile`](../cpanfile).
 
 #### re::engine::RE2
-PBot uses the `re::engine::RE2` module for user-submitted regular expressions.
+Perl's native regular expression engine is susceptible to [ReDoS](https://swtch.com/~rsc/regexp/regexp1.html)
+attacks. To prevent this, PBot uses the `re::engine::RE2` module for user-submitted regular expressions.
 
 If you could not install it through CPAN, you must install it manually.
 
@@ -336,10 +342,12 @@ commands as the built-in PBot console admin user account. This will allow you
 to use admin commands to create new users or join channels.
 
 ### Creating your bot owner admin account
-To create your own fully privileged admin user account, use the following
+To create your own fully privileged admin user account, use the [`useradd`](Commands.md#useradd)
-commands in the PBot terminal console.
+command in the PBot terminal console. Its usage is:
 
-Suppose your nick is `Bob` and your hostmask is `Bob!~user@some.domain.com`.
+    useradd <username> <hostmasks> [channels [capabilities [password]]]
+
+Suppose your nick is `Bob` and your hostmask is `Bob!~user@some.domain.com`. Use the following command:
 
     useradd Bob Bob!~user@*.domain.com global botowner
 
@@ -369,7 +377,7 @@ Now you can use `/msg` in your own IRC client to administrate PBot, instead of
 the terminal console.
 
 ### Adding other users and admins
-To add users to PBot, use the [`useradd`](Admin.md#useradd) command.
+To add users to PBot, use the [`useradd`](Admin.md#useradd) command. Its usage is:
 
     useradd <username> <hostmasks> [channels [capabilities [password]]]
 
@@ -381,7 +389,8 @@ for more information about user-capabilities.
 If you omit the `password` argument, a random password will be generated. The user
 can use the [`my`](Commands.md#my) command to view or change it.
 
-Users may view and change their own metadata by using the [`my`](Commands.md#my) command.
+Users may view and change their own metadata by using the [`my`](Commands.md#my) command,
+provided their hostmask matches the user account.
 
     my [key [value]]