Add useful docs to README.txt

1 files changed, 105 insertions, 1 deletions

diff --git a/README.txt b/README.txt
index b1b1557..26054dd 100644
--- a/README.txt
+++ b/README.txt
@@ -1 +1,105 @@
-slackfacts bot plugins
+limnoria.slackfacts.plugins README
+
+This is a collection of Slackware-specific bot plugins for the
+slackfacts bot, which lives in ##slackware and ##slackware.uk on
+irc.libera.chat.
+
+Commands supported are:
+
+!man - display man page summaries (like "man -f" or "whatis").
+
+!locate - find files in the Slackware package database, and show
+          their locations.
+
+!which - like !locate, but only searches bin/ directories.
+
+!pkgsearch - search for packages by name in the Slackware package
+             database.
+
+!filesearch - find packages containing the given file (similar to
+              "slackpkg file-search").
+
+!srcsearch - given a package name, display the URL for the package's
+             source directory on the slackware.uk mirror.
+
+!pkg - wrapper for !pkgsearch, !filesearch, !srcsearch. slightly less
+       typing involved, but you have to remember the options (see
+       !pkg examples below).
+
+All the commands have help messages, which you can access via
+!help <command> (don't include the ! in <command> though).
+
+Currently only the package database from Slackware 14.2 x86_64 is
+supported.
+
+To avoid spamming the channel, commands that can return multiple
+results are limited to 5 results. If you use a private message to
+run the command, you'll get the results privately, and the limit is
+increased to 25.
+
+Examples:
+
+-- Search all manual sections:
+
+<user> !man printf
+<slackfacts> user: printf(1): format and print data | printf(3): formatted
+             output conversion
+
+-- Search only one manual section:
+
+<user> !man 3 printf
+<slackfacts> user: printf(3): formatted output conversion
+
+-- Find files. This is a substring match, so:
+
+<user> !locate /bin/ls
+<slackfacts> user: /bin/ls | /bin/lsblk | /bin/lsmod [l] | /usr/bin/ls [l] |
+             /usr/bin/lsattr | /usr/bin/lsb [l] | [too many results, only
+             showing first 5]
+
+[Note: symlinks are listed with [l] after the path]
+
+-- Find the ls command:
+
+<user> !which ls
+<slackfacts> user: /bin/ls | /usr/bin/ls [l]
+
+-- Find packages by name, search all categories:
+
+<user> !pkgsearch core
+<slackfacts> user: a/coreutils: core GNU utilities | kde/nepomuk-core:
+             Nepomuk Core utilities and libraries | l/at-spi2-core:
+             Assistive Technology Service Provider Interface core |
+             l/xapian-core: Search Engine Library
+
+With no options, !pkg is a synonym for !pkgsearch.
+
+-- Find packages by name, search one category:
+
+<user> !pkgsearch a/core
+<slackfacts> user: a/coreutils: core GNU utilities
+
+-- Find which package owns a file. This is an exact match if you give an
+   absolute path (if the search term starts with a slash), or a substring
+   match otherwise. You can also use * for globbing (e.g. /bin/ls*).
+
+<user> !filesearch /bin/ls
+<slackfacts> user: a/coreutils: core GNU utilities
+
+!pkg -f is a synonym for !filesearch.
+
+-- Find the source (and SlackBuild) for a package (exact match, no
+globbing/wildcards allowed):
+
+<user> !srcsearch coreutils
+<slackfacts> user:
+             https://slackware.uk/slackware/slackware64-14.2/source/a/coreutils/
+
+!pkg -s is a synonym for !srcsearch.
+
+If there had been an updated coreutils in patches/, the updated version's
+source would have been found. For instance:
+
+<user> !srcsearch irssi
+<slackfacts> user:
+             https://slackware.uk/slackware/slackware64-14.2/patches/source/irssi/