diff --git a/doc/manual.txt b/doc/manual.txt
index 01e36a7c5eb..207810e504c 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -418,6 +418,55 @@ package is downloaded, compiled and installed.
 NOTE: A function defined in a template has preference over the same function
 defined by a `build_style` script.
 
+Build options
+~~~~~~~~~~~~~
+
+Some packages might be built with different build options to enable/disable
+additional features; `xbps-src` allows you to do this with some simple tweaks
+to the `template` file.
+
+The following variables may be set to allow package build options:
+
+*build_options*::
+    Sets the build options supported by the source package.
+
+*build_options_default*::
+    Sets the default build options to be used by the source package.
+
+*desc_option_<option>*::
+    Sets the description for the build option `option`. This must match the
+    keyword set in *build_options*.
+
+After defining those required variables, you can check for the
+`build_option_<option>` variable to know if it has been set and adapt the source
+package accordingly.
+
+The following example shows how to change a source package that uses GNU
+configure to enable a new build option to support PNG images:
+
+-----------------------------------------------------------------------
+# Template file for 'foo'
+pkgname=foo
+version=1.0
+revision=1
+build_style=gnu-configure
+...
+
+# Package build options
+build_options="png"
+desc_option_png="Enable support for PNG images"
+
+if [ "$build_option_png" ]; then
+	configure_args+=" --with-png"
+	makedepends+=" libpng-devel"
+else
+	configure_args+=" --without-png"
+fi
+...
+
+-----------------------------------------------------------------------
+
+
 Contributing via git
 ~~~~~~~~~~~~~~~~~~~~