From 474e18dd94c559a7ead39b6ea78c692e82d1c6d7 Mon Sep 17 00:00:00 2001 From: Pragmatic Software Date: Thu, 15 Jul 2021 09:13:52 -0700 Subject: [PATCH] Update some documentation --- doc/Admin.md | 17 +++++++++-------- doc/FAQ.md | 32 +++++++++++++++++++++++++++++--- doc/QuickStart.md | 27 ++++++++++++++++++--------- 3 files changed, 56 insertions(+), 20 deletions(-) diff --git a/doc/Admin.md b/doc/Admin.md index eea2c507..7b7a2b25 100644 --- a/doc/Admin.md +++ b/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 diff --git a/doc/FAQ.md b/doc/FAQ.md index fb087c62..12c83368 100644 --- a/doc/FAQ.md +++ b/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) ### 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 ### 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 ### 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 @@ -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 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: + + !sh printf "a\nb\nc\nd\ne\n" + a b c d e + + !regset general.preserve_newlines 1 + general.preserve_newlines set to 1 + + !regset general.max_newlines 4 + general.preserve_newlines set to 4 + + !sh printf "a\nb\nc\nd\ne\n" + a + b + c + And that's all I have to say about that. See https://0x0.st/-Okb.txt for full text. diff --git a/doc/QuickStart.md b/doc/QuickStart.md index b19ff1d6..d79c63d2 100644 --- a/doc/QuickStart.md +++ b/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 -commands in the PBot terminal console. +To create your own fully privileged admin user account, use the [`useradd`](Commands.md#useradd) +command in the PBot terminal console. Its usage is: -Suppose your nick is `Bob` and your hostmask is `Bob!~user@some.domain.com`. + useradd [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 [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]]