3 files changed, 115 insertions, 16 deletions
diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
index faf70b1d89..4e50f8f689 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -99,24 +99,30 @@ of the shell script(s) needing fixing. All these names are relative to
 In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed
 from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target.
 
-Example 1:
-
+.Config script: 'divine' package
+================================
 Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
 
-So it's fixup would be:
+So its fixup would be:
 
+--------------------------------
 DIVINE_CONFIG_SCRIPTS = divine-config
+--------------------------------
+================================
 
-Example 2:
-
+.Config script: 'imagemagick' package:
+================================
 Package imagemagick installs the following scripts:
 '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
 
 So it's fixup would be:
 
+--------------------------------
 IMAGEMAGICK_CONFIG_SCRIPTS = \
    Magick-config Magick++-config \
    MagickCore-config MagickWand-config Wand-config
+--------------------------------
+================================
 
 On line 14, we specify the list of dependencies this package relies
 on. These dependencies are listed in terms of lower-case package names,
@@ -358,6 +364,13 @@ LIBFOO_VERSION = 2.32
 Now, the variables that define what should be performed at the
 different steps of the build process.
 
+* +LIBFOO_EXTRACT_CMDS+ lists the actions to be performed to extract
+  the package. This is generally not needed as tarballs are
+  automatically handled by Buildroot. However, if the package uses a
+  non-standard archive format, such as a ZIP or RAR file, or has a
+  tarball with a non-standard organization, this variable allows to
+  override the package infrastructure default behavior.
+
 * +LIBFOO_CONFIGURE_CMDS+ lists the actions to be performed to
   configure the package before its compilation.
 
diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
index 0106df0a84..3736d61248 100644
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -27,8 +27,8 @@ _rebase_ your development branch on top of the upstream tree before
 generating the patch set. To do so, run:
 
 ---------------------
- $ git fetch --all --tags
- $ git rebase origin/master
+$ git fetch --all --tags
+$ git rebase origin/master
 ---------------------
 
 Here, you are ready to generate then submit your patch set.
@@ -36,23 +36,19 @@ Here, you are ready to generate then submit your patch set.
 To generate it, run:
 
 ---------------------
- $ git format-patch -M -n -s -o outgoing origin/master
+$ git format-patch -M -n -s -o outgoing origin/master
 ---------------------
 
 This will generate patch files in the +outgoing+ subdirectory,
 automatically adding the +signed-off-by+ line.
 
-If you want to present the whole patch set in a separate mail, add
-+--cover-letter+ to the previous command line (+man git-format-patch+
-for further information).
-
 Once patch files are generated, you can review/edit the commit message
 before submitting them using your favorite text editor.
 
 Lastly, send/submit your patch set to the Buildroot mailing list:
 
 ---------------------
- $ git send-email --to buildroot@busybox.net outgoing/*
+$ git send-email --to buildroot@busybox.net outgoing/*
 ---------------------
 
 Note that +git+ should be configured to use your mail account.
@@ -62,6 +58,77 @@ Make sure posted *patches are not line-wrapped*, otherwise they cannot
 easily be applied. In such a case, fix your e-mail client, or better,
 use +git send-email+ to send your patches.
 
+Cover letter
+~~~~~~~~~~~~
+
+If you want to present the whole patch set in a separate mail, add
++--cover-letter+ to the +git format-patch+ command (see +man
+git-format-patch+ for further information). This will generate a
+template for an introduction e-mail to your patch series.
+
+A 'cover letter' may be useful to introduce the changes you propose
+in the following cases:
+
+* large number of commits in the series;
+
+* deep impact of the changes in the rest of the project;
+
+* RFC footnote:[RFC: (Request for comments) change proposal];
+
+* whenever you feel it will help presenting your work, your choices,
+  the review process, etc.
+
+Patch revision changelog
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When improvements are requested, the new revision of each commit
+should include a changelog of the modifications between each
+submission. Note that when your patch series is introduced by a cover
+letter, the changelog may be added in the cover letter rather than in
+the individual commits.
+
+When added to the individual commits, this changelog is added when
+editing the commit message.  Below the +Signed-off-by+ section, add
++---+ and your changelog.
+
+Although the changelog will be visible for the reviewers in the mail
+thread, as well as in http://patchwork.buildroot.org[patchwork], +git+
+will automatically ignores lines below +---+ when the patch will be
+merged. This is the intended behavior: the changelog is not meant to
+be preserved forever in the +git+ history of the project.
+
+Hereafter the recommended layout:
+
+---------------
+Patch title less than 80-character length
+
+Some more paragraph giving some more details.
+
+And yet another paragraph giving more details.
+
+Signed-off-by John Doe <john.doe@noname.org>
+---
+Changes v2 -> v3:
+  - foo bar  (suggested by Jane)
+  - bar buz
+
+Changes v1 -> v2:
+  - alpha bravo  (suggested by John)
+  - charly delta
+---------------
+
+Any patch revision should include the version number. The version number
+is simply composed of the letter +v+ followed by an +integer+ greater or
+equal to two (i.e. "PATCH v2", "PATCH v3" ...).
+
+This can be easily handled with +git format-patch+ by using the option
++--subject-prefix+:
+
+---------------------
+$ git format-patch --subject-prefix "PATCH v4" \
+    -M -o outgoing origin/master
+---------------------
+
 Reviewing/Testing patches
 -------------------------
 
diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
index b4a9c123da..c3fd155721 100644
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -29,8 +29,7 @@ The result of the search shows the help message of the matching items.
  $ make help
 --------------------
 
-.Not all targets are always available,
-
+Not all targets are always available,
 some settings in the +.config+ file may hide some targets:
 
 * +linux-menuconfig+ and +linux-savedefconfig+ only work when
@@ -54,12 +53,32 @@ and target trees, the images and the toolchain):
  $ make clean
 --------------------
 
+.Generating the manual:
+
+The present manual sources are located in the 'docs/manual' directory.
+To generate the manual:
+
+---------------------------------
+ $ make manual-clean
+ $ make manual
+---------------------------------
+
+The manual outputs will be generated in 'output/docs/manual'.
+
+.Notes
+- +asciidoc+ is required to build the documentation (see:
+  xref:requirement-optional[]).
+- There is a known issue that you can't build it under Debian Squeeze.
+
+.Reseting Buildroot for a new target:
+
 To delete all build products as well as the configuration:
 
 --------------------
  $ make distclean
 --------------------
 
-Note that if +ccache+ is enabled, running +make clean+ or +distclean+ does
+.Notes
+If +ccache+ is enabled, running +make clean+ or +distclean+ does
 not empty the compiler cache used by Buildroot. To delete it, refer
 to xref:ccache[].