@@ 48,3 48,152 @@ their e-mail address or PGP key used for signing packages. This user
configuration file will be searched using the [XDG Base Directory
Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
which most of the time means it will be located at `~/.config/wkrel/user.yml`.
+
+
+### Package Definition
+
+The YAML file for each package may contain the following top level elements:
+
+| **Element** | **Variable** | **Contents** |
+|:------------|:---------------|:-------------|
+| `package` | `%{package}` | Descriptive name of the package. |
+| `pattern` | `%{pattern}` | Pattern for release files, the `%` character matching the package version. |
+| `gpgkey` | `%{gpgkey}` | PGP key identifier used to sign files. *(Optional.)* |
+| `changelog` | `%{changelog}` | Path to a `NEWS`-like file inside the tarball. *(Optional.)* |
+| `variables` | `%{variables.*}` | Mapping of strings with additional variables. *(Optional.)* |
+| `email` | `%{email.*}` | Mapping for an e-mail configuration. *(Optional. Details below.)* |
+| `files` | `%{files.*}` | Mapping for generated files configuration. *(Optional. Details below.)* |
+
+The following is a minimal example of a self-contained package definition:
+
+```yaml
+# This only makes “wkrel” aware of package files matching the pattern.
+package: Foo Library
+pattern: libfoo-%.tar.xz
+```
+
+A more realistic example, setting the `files` section to allow generating
+a `.sums` file with the package checksums:
+
+```yaml
+package: Bar Library
+pattern: libbar-%.tar.xz
+files:
+ sums: |
+ %{tar.filename} (%{tar.humansize}):
+ sha256: %{tar.sha256sum}
+```
+
+The output for the `sums` file element above can then be obtained as follows:
+
+```sh
+# Generate libbar-1.2.3.tar.xz.sums file
+% wkrel generate path/to/libbar-1.2.3.tar.xz
+
+# Print what would be written to the .sums file
+% wkrel generate path/to/libbar-1.2.3.tar.xz sums
+libbar-1.2.3.tar.xz (532 KiB):
+ sha256: 9fd7bdb45d959a8eb39cc0b83c942759ec08856fe048767b97982d2723518535
+```
+
+
+#### Email Section
+
+The `email` top level element configures how to gnerate release announcements
+to be sent by e-mail. The mapping may contain the following elements:
+
+| **Element** | **Contents** |
+|:------------|:-------------|
+| `sender` | Name and e-mail address of the sender. |
+| `template` | Template text used for the e-mail body. |
+| `subject` | Template used for the e-mail subject. *(Optional.)* |
+
+If the optional `subject` is not specified, the default value
+`"%{package} %{version} released!"` will be used. The following is a valid
+`email` configuration element, note how the `variables` element is used
+to provide a value for the `%{url}` expansion:
+
+```yaml
+variables:
+ url: "https://libfoo.org"
+
+email:
+ sender: "Foo Library release bot <noreply@foolib.org>"
+ subject: "[Release] %{package} %{version} now available"
+ template: |
+ Hello,
+
+ Today %{package} version %{version} has been released.
+ You can find the full announcement at:
+
+ %{url}/releases/%{version}.html
+
+ The release team,
+ %{date}
+```
+
+
+### Files Section
+
+The `files` top level element is a mapping of strings to
+[templates](#Templates). For each element, it is possible to generate a
+companion file to a release package, with its contents being the result from
+expanding the associated template.
+
+```yaml
+files:
+ sums: "sha256 %{tar.sha256sum} %{tar.filename}"
+ news: |
+ # Changes in the %{version} release
+
+ %{release-notes}
+```
+The `wkrel generate` subcommand can be used to generate the results from
+processing the configured templates.
+
+
+### Templates
+
+Certain configuration values are taken as templates, which may reference
+[variables](#Variables). Variables are references by enclosing their name
+inside a pair of brackets prefixed by a percent sign: `%{…}`. Variables may
+contain any alphanumeric character, dashes (`-`), and underscores (`_`). The
+dot (`.`) character can be used to access subelements of variables which
+behave like mappings. The following are valid examples:
+
+- `%{date}` expands to a generatd value corresponsing to the current date.
+- `%{package}` expands to the value of the `package` configuration value.
+- `%{email.sender}` expands to the `sender` configuration item of the
+ `email` configuration value (which is a mapping).
+
+All configuration values are made available as variables, which means that
+both `%{name}` and `%{variables.name}` will expand to the same value.
+
+
+#### Variables
+
+The following variables are available for expansion in
+[templates](#Templates):
+
+- Named values configured in the top level `variables` element.
+- Cofiguration [top level elements](#Package Definition).
+- Extra generated content from the table below.
+
+| **Variable** | **Contents** |
+|:-------------|:-------------|
+| `%{date}` | The current date e.g. `April 2nd, 2019`. |
+| `%{release-notes}` | Release notes extracted from the file specified by the `changelog` configuration item. |
+| `%{release-tagline}` | String indicating the maturity of the release, e.g. `This is a stable release in the 1.4 series.`. |
+| `%{version}` | Package version string i.e. the part matched by `%` from the `pattern`. |
+| `%{tar.*}` | Information about the package tarball file. |
+
+The package tarball object (`%{tar.*}`) provides the following variables:
+
+| **Variable** | **Contents** |
+|:-------------|:-------------|
+| `%{tar.filename}` | File name, without the leading path components. |
+| `%{tar.humansize}` | File size, with one decimal and magnitude suffix e.g. `1.3 MiB`. |
+| `%{tar.size}` | File size, in bytes. |
+| `%{tar.md5sum}` | MD5 checksum of the file data. |
+| `%{tar.sha1sum}` | SHA1 checksum of the file data. |
+| `%{tar.sha256sum}` | SHA255 checksum of the file data. |