Describe configuration options

2 files changed, 55 insertions, 0 deletions

diff --git a/README.md b/README.md
index 462c692..88a281b 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,8 @@ SlackBuilder is a tool which aims to help to update Slackware packages.
 It checks for the latest version of an upstream package and can modify
 SlackBuild meta information accordingly.
 
+## Features
+
 ## Build instructions
 
 SlackBuilder is a Haskell program and can be built and run using the
@@ -17,9 +19,12 @@ After that you can run slackbuilder using Cabal and `cabal run slackbuilder`.
 Or you can install the program locally with `cabal install` and run it just
 as `slackbuilder` assuming `~/.cabal/bin` is on your PATH.
 
+# Usage
+
 ## Configuration
 
 There is a sample configuration file under `config/config.toml.example`.
+The sample contains comments describing each supported option.
 Just copy this file to `config/config.toml` and modify as needed.
 
 Each package that should be updated automatically needs a special
@@ -33,3 +38,26 @@ itself.
 
 For the time being `src/Main.hs` contains descriptions of my
 slackbuilds, that can be used as an example and a start point.
+
+## Command line options
+
+SlackBuilder is called with a command as its first argument:
+
+```sh
+slackbuilder COMMAND
+```
+
+Currently supported commands are listed below.
+
+### check
+
+`check` checks whether there are updates available. It prints the name of each
+known package together with its version. If the package version is not the
+latest known version, the version the package can be updated to is printed as
+well.
+
+### up2date
+
+Performs the package updates for packages the can be updated. `up2date` accepts
+an optional argument specifying the package that should be updated if only one
+package should be updated and not all.
diff --git a/config/config.toml.example b/config/config.toml.example
index e2ef02e..2c9b4d4 100644
--- a/config/config.toml.example
+++ b/config/config.toml.example
@@ -1,8 +1,35 @@
+## Global options
+
+# Accessing GitHub APIs is only possible using a personal access token. The
+# token doesn't need any scopes set since it is used to query public
+# repositories.
 gh_token = ""
+
+# Relative path to a cloned SBo repository.
 repository = "./slackbuilds"
+
+# After one package is updated a commit is created on this branch. The branch is
+# not pushed or reset automatically.
 branch = "user/nick/updates"
+
+# If some packages use custom sources and these sources a generated during the
+# update, this option specifies the base URL where the sources can be downloaded
+# afterwads. The full URL written into the .info file contains download_url,
+# followed by the package name and source file name. This option should probably
+# be configured consistently with the remote_path.
 download_url = "https://example.com/some/path"
+
+# If a package updater generates a source tarball, the tarball is uploaded to
+# a remote destination with scp. remote_path specifies the remote server and
+# a local path on the server where the source tarballs are hosted. When
+# uploading the remote_path is followed by the package name and source file
+# name. To specify a public URL where the sources can be downloaded, see
+# download_url.
 remote_path = "example.com:/srv/httpd/some/path"
 
+## Maintainer specific options
 [maintainer]
+
+# Whether the git commits should be signed with a GPG signature using the
+# default key.
 signature = false