GitHub/pbot
3
0
Fork 0
mirror of https://github.com/pragma-/pbot.git synced 2024-12-23 11:12:42 +01:00
Code Issues Projects Releases Wiki Activity

Update some documentation

Browse Source
This commit is contained in:
Pragmatic Software 2021-07-15 09:13:52 -07:00
parent faa614d07d
commit 474e18dd94
3 changed files with 56 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
doc/Admin.md
View File

@ -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

32
doc/FAQ.md
View File

@ -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.

27
doc/QuickStart.md
View File

@ -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 <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]]