update docs

2 files changed, 56 insertions, 12 deletions

diff --git a/QUICKSTART b/QUICKSTART
new file mode 100644
index 0000000..47d7d52
--- /dev/null
+++ b/QUICKSTART
@@ -0,0 +1,21 @@
+See README for install instructions. Once you have
+sbo-maintainer-tools installed:
+
+You can lint the build you're working on currently by running
+"sbolint" while cd'ed into its directory.
+
+You can lint the *package* (if you've already built one) by running
+"sbopkglint" in the build directory (and entering your password, if
+you're asked for one).
+
+You can also lint any package by giving its filename as an argument
+to sbopkglint. If you have a bunch of already-built packages, you can
+lint them all at once with e.g. "sbopkglint /tmp/*.tgz".
+
+sbolint and sbopkglint each have extensive man pages and --help
+output, which you'll want to read to learn to use the tools
+effectively.
+
+You should also read the sbo-maintainer-tools README, if you haven't
+already. In particular, the README tells you how to set up the git
+hook (which is *very* handy, if you use git).
diff --git a/README b/README
index 7c06d83..ed255c2 100644
--- a/README
+++ b/README
@@ -2,32 +2,44 @@ sbo-maintainer-tools
 --------------------
 
 These are "lint" tools to make life easier for SlackBuilds.org
-maintainers and admins.
+maintainers and admins. They check your builds and packages for
+various problems, so your builds will be higher quality, and there
+will be less work for the admins to do when reviewing your build for
+approval.
 
 Included tools:
 
 - sbolint: checks your SlackBuild, README, .info file, and slack-desc.
-  Also there's a git pre-commit hook you should use, that automatically
-  calls sbolint and stops you from committing bad code.
 
 - sbopkglint: checks your package, after it's built.
 
+- pre-commit-sbolint: a git pre-commit hook you should use, that
+  automatically calls sbolint and stops you from committing bad code.
+
 Note that the SBo admins use these tools as part of the approval
 process, when you submit an update. Failure to pass the lint checks
 is a valid reason for rejecting your submission, so you should either
 make sure your scripts and packages pass the tests, or give a good
 explanation why a failure isn't relevant to your build (because the
-tests aren't perfect, of course).
+tests aren't perfect, of course, and there are exceptions to almost
+every rule).
 
 Installation:
 
-The best way to install sbo-maintainer-tools is to install them from
-SBo (system/sbo-maintainer-tools).
+The easiest way to install sbo-maintainer-tools is to install them
+from SBo (system/sbo-maintainer-tools). The SBo build might be out
+of date, so you might want to get the latest version from git and
+install it manually:
+
+  git clone https://slackware.uk/~urchlay/repos/sbo-maintainer-tools
+  cd sbo-maintainer-tools
+  make install  # add PREFIX=/usr if you hate using /usr/local
 
-If you prefer, you can install them with "make install" (defaults to
-/usr/local; add 'PREFIX=/usr' if you'd rather). You can also run them
-directly from the source directory, if you can think of a reason for
-that (e.g. if you're hacking on the tests).
+You can also run sbolint and sbopkglint directly from the source
+directory (e.g. ./sbopkglint), if you can think of a reason for that
+(maybe you're hacking on the tests).
+
+Git Hook:
 
 To use the git hook, copy pre-commit-sbolint to .git/hooks/pre-commit
 in your git work tree (wherever you cloned the SBo repository),
@@ -36,5 +48,16 @@ pre-commit hook, you can copy/paste the code, or (possibly) just
 append pre-commit-sbolint to your existing hook (if it doesn't end
 with "exit 0").
 
-For more information, see the sbolint and sbopkglint man pages (or run
-the scripts with --doc; it's the same thing).
+If you absolutely must commit code that doesn't pass sbolint, you can
+set SBOLINT=no in the environment, e.g.
+
+  SBOLINT=no git commit -m'Message here' ...
+
+If you find yourself having to do this often, please contact the SBo
+admins and explain the situation; it may mean sbolint needs updating.
+
+Documentation:
+
+For more information, see the sbolint and sbopkglint man pages (or
+run the scripts with --doc; it's the same thing). There's also a
+QUICKSTART file that gives the bare minimum info to get started.