doc/manual.txt: multiple improvements and tweaks.

doc/manual.txt

@@ -1,3 +1,5 @@
+// vim: set syntax=asciidoc:
+
 The XBPS source packages manual
 ===============================
 Juan RP <xtraeme@gmail.com>
@@ -8,7 +10,7 @@ Juan RP <xtraeme@gmail.com>
 :website: http://www.voidlinux.eu
 
 This article contains an exhaustive manual of how to create new source
-packages for XBPS, the package manager of the *Void Linux distribution*.
+packages for XBPS, the `Void Linux` native packaging system.
 
 Introduction
 ------------
@@ -131,7 +133,7 @@ The following functions are defined by `xbps-src` and can be used on any templat
     `vmkdir <directory> [<mode>]`
 
 Creates a directory in `$DESTDIR` (if called from a `source section`) or
-    $PKGDESTDIR` (if called from a `package section`). The 2nd optional argument
+`$PKGDESTDIR` (if called from a `package section`). The 2nd optional argument
 sets the mode of the directory.
 
 NOTE: shell wildcards must be properly quoted.
@@ -292,7 +294,8 @@ Optional variables
 *make_install_args*::
  The arguments to be passed in to `${make_cmd}` at the `install-destdir`
 phase if `${build_style}` is set to `configure`, `gnu-configure` or
-    `gnu_makefile` build methods. Unset by default.
+`gnu_makefile` build methods. By default set to
+`PREFIX=/usr DESTDIR=${DESTDIR}`.
 
 *make_build_target*::
  The target to be passed in to `${make_cmd}` at the build phase if
@@ -302,7 +305,7 @@ Optional variables
 *make_install_target*::
  The target to be passed in to `${make_cmd}` at the `install-destdir` phase
 if `${build_style}` is set to `configure`, `gnu-configure` or `gnu_makefile`
-    build methods. By default set to `DESTDIR=${DESTDIR} install`.
+build methods. By default set to `install`.
 
 *patch_args*::
  The arguments to be passed in to the `patch(1)` command when applying
@@ -351,10 +354,13 @@ The current list of available `build_style` scripts is the following:
  For packages that use GNU make, build arguments can be passed in via
 `make_build_args` and install arguments via `make_install_args`. The build
 target can be overriden via `make_build_target` and the install target
+via `make_install_target`.
 
 *meta*::
  For `meta-packages`, i.e packages that only install local files or simply
-    depend on additional packages.
+depend on additional packages. This build style does not install
+dependencies to the root directory, and only checks if a binary package is
+available in repositories.
 
 *perl-ModuleBuild*::
  For packages that use the Perl
@@ -373,6 +379,9 @@ The current list of available `build_style` scripts is the following:
 *waf*::
  For packages that use the Python `waf` method with python2.
 
+NOTE: if `build_style` is not set, the template must (at least) define a
+`do_install()` function and optionally more phases via `do_xxx()` functions.
+
 Functions
 ~~~~~~~~~
 The following functions can be defined to change the behavior of how the
@@ -418,41 +427,8 @@ 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.
 
-Run-time dependencies
-~~~~~~~~~~~~~~~~~~~~~
-
-Dependencies for ELF executables or shared libraries are detected
-automatically by `xbps-src`, hence run-time dependencies must not be specified
-in the *package sections* with the following exceptions:
-
-- ELF binaries using dlopen(3).
-- non ELF objects, i.e perl/python/ruby/etc modules.
-- Overriding the minimal version specified in the `shlibs` file.
-
-The run-time dependencies for ELF binaries are detected by checking which SONAMEs
-use and then the SONAMEs are mapped to a binary package name with a minimal
-required version. The `shlibs` file in the `xbps-packages/common` directory
-sets up the `SONAME pkgname>=version` mappings.
-
-For example the `foo-1.0_1` package provides the `libfoo.so.1` SONAME and
-software requiring this library will link to `libfoo`; the resulting binary
-package will have a run-time dependency to `foo>=1.0_1` package as specified in
-`common/shlibs`:
-
------------------------
-# common/shlibs
-...
-libfoo.so.1 foo-1.0_1
-...
------------------------
-
-- The first field specifies the SONAME.
-- The second field specified the package name and minimal version required.
-- A third optional field specifies the architecture (rarely used).
-
 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.
@@ -533,9 +509,69 @@ The build options can also be shown for binary packages via `xbps-query(8)`:
 $ xbps-query -R --property=build-options foo
 --------------------------------------------
 
-Contributing via git
-~~~~~~~~~~~~~~~~~~~~
+Package section
+---------------
+Mandatory functions
+~~~~~~~~~~~~~~~~~~~
+A `package section` needs at least one mandatory function matching the
+`$pkgname` of the `source section`: `<pkgname>_package()`. Multiple binary
+packages with the same template can be created by adding additional
+`<pkg>_package()` functions.
 
+Those `<pkg>_package()` functions are run in alphabetical order, with the
+exception of the `<pkgname>_package()` function, which is always the last one.
+
+Optional variables
+~~~~~~~~~~~~~~~~~~
+*conf_files*::
+A list of configuration files the binary package owns; this expects full
+paths, and multiple entries can be separated by blanks, i.e:
+`conf_files="/etc/foo.conf /etc/foo2.conf"`.
+
+*noarch*::
+ If set, the binary package is not architecture specific and can be shared
+by all supported architectures.
+
+*nonfree*::
+ If set, the binary package will be put into the *non free* repository.
+
+*nostrip*::
+ If set, the ELF binaries with debugging symbols won't be stripped. By
+default all binaries are stripped.
+
+Run-time dependencies
+---------------------
+Dependencies for ELF executables or shared libraries are detected
+automatically by `xbps-src`, hence run-time dependencies must not be specified
+in the *package sections* with the following exceptions:
+
+- ELF binaries using dlopen(3).
+- non ELF objects, i.e perl/python/ruby/etc modules.
+- Overriding the minimal version specified in the `shlibs` file.
+
+The run-time dependencies for ELF binaries are detected by checking which SONAMEs
+use and then the SONAMEs are mapped to a binary package name with a minimal
+required version. The `shlibs` file in the `xbps-packages/common` directory
+sets up the `SONAME pkgname>=version` mappings.
+
+For example the `foo-1.0_1` package provides the `libfoo.so.1` SONAME and
+software requiring this library will link to `libfoo`; the resulting binary
+package will have a run-time dependency to `foo>=1.0_1` package as specified in
+`common/shlibs`:
+
+-----------------------
+# common/shlibs
+...
+libfoo.so.1 foo-1.0_1
+...
+-----------------------
+
+- The first field specifies the SONAME.
+- The second field specified the package name and minimal version required.
+- A third optional field specifies the architecture (rarely used).
+
+Contributing via git
+--------------------
 You can fork the `xbps-packages` git repository on github and then set up
 a remote to pull in new changes:
 
@@ -556,8 +592,12 @@ for more information.
 
 For commit messages please use the following rules:
 
-- If you've imported a new package use `New package: <pkgver>`.
-- If you've updated a package use `<pkgname>: updated to <version>`.
-- If you've removed a package use `<pkgname>: removed ...`.
-
+- If you've imported a new package use `"New package: <pkgver>"`.
+- If you've updated a package use `"<pkgname>: updated to <version>"`.
+- If you've removed a package use `"<pkgname>: removed ..."`.
+- If you've modified a package use `"<pkgname>: ..."`.
 
+Help
+----
+If after reading this `manual` you still need some kind of help, please join
+us at `#xbps` via IRC at `irc.freenode.net`.