--- a/Docs/manual.md	Wed Aug 21 16:40:27 2019 +0200
+++ b/Docs/manual.md	Wed Aug 21 20:45:00 2019 +0200
@@ -139,21 +139,17 @@
 Options
 =======
 
-...
-
-Example with network/wget:
-
-	# cd network/wget
-	# SSL=openssl NLS=no vpk build
+If the package offer build options, edit the *PKGOPTIONS* variable and always
+add default values that match upstream if possible. Boolean options must always
+be considered as *yes* or *no*. If an option requires a list, use a space
+separated list of values.
 
-Add the desired options in *PKGOPTIONS* variable and don't forget to set default
-values.
+Example:
 
-Example with NLS
-
-	PKGOPTIONS="NLS"
+	PKGOPTIONS="NLS DRIVERS"
 
 	: ${NLS:=yes}
+	: ${DRIVERS:=amd intel}
 
 	if [ "$NLS" = "yes" ]; then
 		PKGDEPENDS="core/gettext $PKGDEPENDS"
@@ -180,13 +176,14 @@
 The package must ensure appropriate directories for installing files. This
 includes:
 
-- /etc/rc.d for service files
-- /lib/pkgconfig: for .pc files
-- /lib/cmake: for CMake config files
-- /lib: for libraries (no lib64 suffix)
-- /share/locale: for NLS files
-- /share/man/man{1,2,3,4,5,6,7,8}: for man pages (in uncompressed form)
-- /share/doc/PKGNAME (exact directory, no version)
+- /etc/rc.d: for service files,
+- /lib/pkgconfig: for .pc files,
+- /lib/cmake: for CMake config files,
+- /lib: for libraries (no lib64 suffix),
+- /share/PKGNAME: data directory (if applicable),
+- /share/locale: for NLS files,
+- /share/man/man{1,2,3,4,5,6,7,8}: for man pages (in uncompressed form),
+- /share/doc/PKGNAME (exact directory, no version): arbitrary documentation.
 
 Keep neutral
 ============
@@ -195,64 +192,130 @@
 possible. Only minor tweaks are allowed including:
 
 - adjusting pid/uid/gid in a default configuration file for easier deployment
-  (but not on the original file example)
-- disabling static libraries
-- making sure paths are consolidated
-- making sure system libraries are used rather than in-source bundles
+  (but not on the original file example),
+- making sure paths are consolidated,
+- making sure system libraries are used rather than in-source bundles,
+- replacing PAM files (see below).
+
+PAM files
+=========
+
+The PAM system is an flexible and well designed authentication tool, it has a
+large number of modules and configuration settings. This complexity leads to
+inconsistent upstream PAM files that are not always compatible with the default
+Vanilla Linux generic's files, therefore you *must* always replace the provided
+PAM files with custom alternatives and sane defaults. In general, LFS is a good
+recommandation regarding PAM files.
+
+Also, don't forget to add PAM files to the *PKGPROTECT* variable as they are
+meant to be edited by the system administrator.
+
+Patches
+=======
+
+If a software requires patching, always try to see if there is already an
+upstream patch that fixes the issue. If not, you may check how other Linux
+distributions fix the problem with a local workaround.
+
+Then, please consider sending the patch to the upstream if applicable.
+
+Patches must be named in the form *patch-category.patch*. We encourage old style
+of patches that you usually create by editing the file and comparing with the
+original one.
+
+Example:
+
+	cp Makefile.orig Makefile
+	vim Makefile
+	diff -ub Makefile.orig Makefile > patch-musl.patch
+
+Warning: by default busybox patch is used and is much stricter than standalone
+         counterpart, in doubt always try to apply the patch manually with
+         busybox patch and edit if required.
+
+The following names are recommended depending on the situation:
+
+- patch-fhs.patch: when a patch is required to adapt installation/usage to the
+  Vanilla Linux file system hierarchy,
+- patch-musl.patch: when the code assume a glibc specific code,
+- patch-clang.patch: when the code does not compile with LLVM/Clang. Make sure
+  the patch does not break GCC, if it does apply the patch in a conditional.
+
+Also, do not create a patch for individual files if they all belong to the same
+category. For example, if several source files require patching to build against
+musl, use only one *patch-musl.patch* file.
 
 Services
 ========
 
-Services files must be installed in /etc/rc.d. You must use the following
-conventions regarding messages the service will print.
+Services files must be installed in /etc/rc.d in the mode 0644.
+
+Example:
+
+	install -Dm0644 food $DESTDIR/etc/rc.d/food
 
 The script must at least support start, stop and restart.
 
-#### start (required)
+UX style
+--------
+
+You must use the following conventions regarding messages the service will
+print.
+
+### start (required)
 
 Always add arguments with the invocation.
 
-    Starting foo: /bin/foo -d
+	Starting foo: /bin/foo -d
+
+If the service is already running, show:
 
-#### stop (required)
+	foo is already running with pid: 1234
+
+### stop (required)
 
 If the service is not running, don't write any message. Otherwise write:
 
-    Stopping foo.
+	Stopping foo.
 
-#### restart (required)
+### restart (required)
 
 Basically, this command just calls stop and start.
 
-    Stopping foo.
-    Starting foo: /bin/foo -d
+	Stopping foo.
+	Starting foo: /bin/foo -d
 
-#### status
+### status (recommended)
 
 Depending on the status, write the following messages.
 
-    foo is running with pid: 1234
-    foo is not running
+	foo is running with pid: 1234
+	foo is not running
 
-#### usage
+### usage (required)
 
 If the script is invoked with invalid arguments or none, write the usage like
 this through stderr and exit 1. Also keep all subcommands sorted.
 
-    usage: foo restart|start|status|stop
+	usage: foo restart|start|status|stop
 
 If your script may support additional operations, messages and usage are up to
 the maintainer discretion.
 
 See also the template file in Templates/rc.
 
-Libraries
-=========
+Libtool files
+=============
+
+Do not ship libtool files.
 
-Do not ship static libraries and libtool files. Make sure your build script
-suppress static builds if possible or delete the .a file.
+Manual pages
+============
 
-Note: the C and C++ library are shipped for technical reasons though.
+Do never install compressed manual pages. The `vpk` tool performs automatic
+compression on installation depending on the user setting. Check how to disable
+compression in the package or decompress them after installation in the
+destination directory.
 
 Post install scripts
 ====================
@@ -269,7 +332,7 @@
 - post-uninstall: after the removal of the package.
 
 Note: if the package wants to call a binary from an other package, it is usually
-a good idea to check it's presence first.
+      a good idea to check it's presence first.
 
 Example: