[PATCH 3/4] doc: update user-manual.md

[Henning Schild <henning.schild@siemens.com>]

The introduction of 'dpkg-raw.bbclass' changed the way people can
customize their images. Cover the new way in the manual. Along the way
also fix a few mistakes and slightly change structure.

Signed-off-by: Henning Schild <henning.schild@siemens.com>
---
 doc/user_manual.md | 52 +++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 43 insertions(+), 9 deletions(-)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index 4707a68..e2837c4 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -254,9 +254,9 @@ Isar workflow consists of stages described below.
 
 This filesystem is used as a build environment to compile custom packages. It is generated using `apt` binaries repository, selected by the user in configuration file. Please refer to distro configuration chapter for more information.
 
-### Custom Package Compilation
+### Custom Package Generation
 
-During this stage Isar processes custom packages selected by the user and generates binary `*.deb` packages for the target. Please refer to custom packages compilation section for more information.
+During this stage Isar processes custom packages selected by the user and generates binary `*.deb` packages for the target. Please refer to custom packages generation section for more information.
 
 ### Generation of Basic Target Filesystem
 
@@ -336,14 +336,14 @@ DISTRO = "distro-name"
 
 ---
 
-## Custom Package Compilation
+## Custom Package Generation
 
-Isar provides possibility to compile and install custom packages. The current version supports only building `deb` packages using `dpkg-buildpackage`, so the sources should contain the `debian` directory with necessary meta information. To add new package to image, it needs the following:
+To add new package to an image, do the following:
 
- - Create package recipe and put it in your `isar` layer.
+ - Create a package recipe and put it in your `isar` layer.
  - Append `IMAGE_INSTALL` variable by this recipe name. If this package should be included for all the machines, put `IMAGE_INSTALL` to `local.conf` file. If you want to include this package for specific machine, put it to your machine configuration file.
 
-Please refer to `add custom application` section for more information about writing recipes.
+Please refer to `Add a Custom Application` section for more information about writing recipes.
 
 ---
 
@@ -484,12 +484,18 @@ Isar contains two image type classes that can be used as reference:
 
 ## Add a Custom Application
 
-Before creating new recipe it's highly recommended to take a look into the BitBake user manual mentioned in Terms and Definitions section.
+Before creating a new recipe it's highly recommended to take a look into the BitBake user manual mentioned in Terms and Definitions section.
 
-Current Isar version supports building packages in Debian format only. The package must contain the `debian` directory with the necessary metadata.
+Isar currently supports two ways of creating custom packages.
 
-A typical Isar recipe looks like this:
+### Compilation of debianized-sources
 
+The `deb` packages are built using `dpkg-buildpackage`, so the sources should contain the `debian` directory with necessary meta information. This way is the default way of adding software that needs to be compiled from source. The bbclass for this approach is called `dpkg`.
+
+**NOTE:** If the sources do not contain a `debian` directory your recipe can fetch, create, or ship that.
+
+
+#### Example
 ```
 DESCRIPTION = "Sample application for ISAR"
 
@@ -523,3 +529,31 @@ This approach prevents duplication of the license files in different packages.
  - `SRC_REV` - Source code revision to fetch. Please check the BitBake user manual for supported download formats.
 
 The last line in the example above adds recipe to the Isar work chain.
+
+### Packages without source
+
+If your customization is not about compiling from source there is a second way of creating `deb` packages. That way can be used for cases like:
+
+ - packaging binaries/files that where built outside of Isar
+ - customization of the rootfs with package-hooks
+ - pulling in dependancies (meta-packages)
+
+The bbclass for this approach is called `dpkg-raw`.
+
+#### Example
+```
+DESCRIPTION = "Sample application for ISAR"
+MAINTAINER = "Your name here <you@domain.com>"
+DEBIAN_DEPENDS = "apt"
+
+inherit dpkg-raw
+
+do_populate_package() {
+....
+}
+```
+For the variables please have a look at the previous example, the following new variables are used in this recipe:
+ - `MAINTAINER` - The maintainer of the `deb` package we create
+ - `DEBIAN_DEPENDS` - Debian packages that the package depends on
+
+Have a look at the `example-raw` recipe to get an idea how the `dpkg-raw` class can be used to customize your image.
-- 
2.13.5