[Buildroot] [PATCH 0 of 8 RFCv2 for 2014.08] manual: restructuring and improvements

[Buildroot] [PATCH 0 of 8 RFCv2 for 2014.08] manual: restructuring and improvements

[Thomas De Schampheleire]

This patch series improves the manual by
a. reworking the overall structure
b. improving certain sections wrt clarity and wording

At this point, this is still an RFC as I did not yet go through the entire
manual. Currently, the overall structure is clear, and the Getting started
part is finished. During the rest of the month I will cover the User guide
and Developer guide.
One of the final patches (not yet included) will reorganize the manual
source files themselves. Currently, I'm keeping the current names to ease
reviewing.

It is my goal to make sure this series is in a mergable state before the
release of 2014.08. If you have any comments or objections against these
changes, please let me know as soon as possible...

Thanks for your feedback!


Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
Thomas De Schampheleire (8)
  manual: high-level restructuring
  manual: remove 'Events' section
  manual/getting started: rename and move 'Getting involved' section
  manual/getting started: rework 'Community resources' section
  manual/getting started: rework 'System requirements' section
  website/download: update daily snapshot section
  manual/getting started: rework 'Getting Buildroot' section
  manual/getting started: rework 'Using Buildroot' section

 docs/download.html                          |   13 +-
 docs/manual/advanced.txt                    |    2 +-
 docs/manual/appendix.txt                    |    2 -
 docs/manual/beyond-buildroot.txt            |    8 +-
 docs/manual/ccache-support.txt              |    2 +-
 docs/manual/contribute.txt                  |   53 +++++--
 docs/manual/developer-guide.txt             |    2 -
 docs/manual/download-location.txt           |    2 +-
 docs/manual/faq-troubleshooting.txt         |   16 +-
 docs/manual/get-involved.txt                |  146 ++++++-------------
 docs/manual/getting.txt                     |   26 +--
 docs/manual/going-further.txt               |    2 +-
 docs/manual/how-buildroot-works.txt         |    2 +-
 docs/manual/introduction.txt                |    2 +-
 docs/manual/known-issues.txt                |    2 +-
 docs/manual/legal-notice.txt                |    8 +-
 docs/manual/manual.mk                       |    4 +-
 docs/manual/manual.txt                      |   14 +-
 docs/manual/package-make-target.txt         |    2 +-
 docs/manual/prerequisite.txt                |   40 +++--
 docs/manual/starting-up.txt                 |    2 -
 docs/manual/using-buildroot-debugger.txt    |    2 +-
 docs/manual/using-buildroot-development.txt |    2 +-
 docs/manual/using-buildroot-toolchain.txt   |    2 +-
 docs/manual/using.txt                       |   59 ++++---
 docs/manual/working-with.txt                |    2 -
 26 files changed, 196 insertions(+), 221 deletions(-)

[Buildroot] [PATCH 1 of 8 RFCv2 for 2014.08] manual: high-level restructuring

[Thomas De Schampheleire]

The structure of the buildroot manual is not always clear. There is a large
number of chapters, and some chapters seem to overlap. The distinction
between general usage and developer information is not always clear.

This patch restructures the manual into four large parts:
- getting started
- user guide
- developer guide
- appendix

Except for the names of these parts, the section names are not yet changed.
Content-wise there are no changes yet either. This will be handled in
subsequent patches.

In order to achieve the introduction of a new level 'parts' above
'chapters', the section indicators (=, ==, ===, ...) of several sections
have to be moved one level down. Additionally, the leveloffset indication to
asciidoc has to be removed. Finally, to maintain more or less the same level
of detail in the table of contents, the toc.section.depth attribute is
reduced as well. Note that for some sections, less detail is visible now.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/advanced.txt                    |   2 +-
 docs/manual/appendix.txt                    |   2 --
 docs/manual/beyond-buildroot.txt            |   8 ++++----
 docs/manual/ccache-support.txt              |   2 +-
 docs/manual/contribute.txt                  |  18 +++++++++---------
 docs/manual/developer-guide.txt             |   2 --
 docs/manual/download-location.txt           |   2 +-
 docs/manual/faq-troubleshooting.txt         |  16 ++++++++--------
 docs/manual/get-involved.txt                |  26 +++++++++++++------------
 docs/manual/going-further.txt               |   2 +-
 docs/manual/how-buildroot-works.txt         |   2 +-
 docs/manual/introduction.txt                |   2 +-
 docs/manual/known-issues.txt                |   2 +-
 docs/manual/legal-notice.txt                |   8 ++++----
 docs/manual/manual.mk                       |   4 ++--
 docs/manual/manual.txt                      |  12 +++++++++---
 docs/manual/package-make-target.txt         |   2 +-
 docs/manual/starting-up.txt                 |   2 --
 docs/manual/using-buildroot-debugger.txt    |   2 +-
 docs/manual/using-buildroot-development.txt |   2 +-
 docs/manual/using-buildroot-toolchain.txt   |   2 +-
 docs/manual/working-with.txt                |   2 --
 22 files changed, 60 insertions(+), 62 deletions(-)


Some notes:
- It is my goal to get the restructured manual in shape for inclusion
  into 2014.08. I will need your feedback to achieve this.

- I did not yet rename or restructure the files in docs/manual. I first want
  to get an approval on the layout. Note that the current organization of
  contents into files reflects the structure a bit too much IMO, with some
  files simply including other files but not adding content. This makes it
  difficult to reorganize.
  I am considering to flatten the file organization to address this problem.

- I'm planning subsequent patches to join some sections together, update
  some section titles, and if needed address the content itself.
  Additionally, I'm considering to remove the 'Events' section as it is not
  up-to-date and hard to maintain. The wiki is better suited for such type
  of information, IMO.

- Taking into account the above notes, I'm currently not expecting a deep
  review, since many things are yet to change. Rather, I simply need your
  opinion on the direction I'm taking with respect to organization and the
  proposed structure.
  Your concerns or requests with respect to subsequent patches are of course
  also welcome.


For easy reviewing, the original table of contents was:

1. About Buildroot
2. Starting up
    2.1. System requirements
        2.1.1. Mandatory packages
        2.1.2. Optional packages
    2.2. Getting Buildroot
    2.3. Using Buildroot
3. Working with Buildroot
    3.1. Details on Buildroot configuration
        3.1.1. Cross-compilation toolchain
        3.1.2. /dev management
        3.1.3. init system
    3.2. make tips
    3.3. Customization
        3.3.1. Customizing the generated target filesystem
        3.3.2. Customizing the BusyBox configuration
        3.3.3. Customizing the uClibc configuration
        3.3.4. Customizing the Linux kernel configuration
        3.3.5. Customizing the toolchain
    3.4. Storing the configuration
        3.4.1. Basics for storing the configuration
        3.4.2. Creating your own board support
        3.4.3. Step-by-step instructions for storing configuration
        3.4.4. Customizing packages
        3.4.5. Keeping customizations outside Buildroot
    3.5. Daily use
        3.5.1. Understanding when a full rebuild is necessary
        3.5.2. Understanding how to rebuild packages
        3.5.3. Offline builds
        3.5.4. Building out-of-tree
        3.5.5. Environment variables
        3.5.6. Dealing efficiently with filesystem images
        3.5.7. Graphing the dependencies between packages
        3.5.8. Graphing the build duration
    3.6. Integration with Eclipse
    3.7. Hacking Buildroot
4. Frequently Asked Questions & Troubleshooting
    4.1. The boot hangs after Starting network?
    4.2. Why is there no compiler on the target?
    4.3. Why are there no development files on the target?
    4.4. Why is there no documentation on the target?
    4.5. Why are some packages not visible in the Buildroot config menu?
    4.6. Why not use the target directory as a chroot directory?
    4.7. Why doesn?t Buildroot generate binary packages (.deb, .ipkg?)?
5. Known issues
6. Going further in Buildroot?s innards
    6.1. How Buildroot works
    6.2. Advanced usage
        6.2.1. Using the generated toolchain outside Buildroot
        6.2.2. Using gdb in Buildroot
        6.2.3. Using ccache in Buildroot
        6.2.4. Location of downloaded packages
        6.2.5. Package-specific make targets
        6.2.6. Using Buildroot during development
7. Developer Guidelines
    7.1. Coding style
        7.1.1. Config.in file
        7.1.2. The .mk file
        7.1.3. The documentation
    7.2. Adding new packages to Buildroot
        7.2.1. Package directory
        7.2.2. Config.in file
        7.2.3. The .mk file
        7.2.4. The .hash file
        7.2.5. Infrastructure for packages with specific build systems
        7.2.6. Infrastructure for autotools-based packages
        7.2.7. Infrastructure for CMake-based packages
        7.2.8. Infrastructure for Python packages
        7.2.9. Infrastructure for LuaRocks-based packages
        7.2.10. Infrastructure for Perl/CPAN packages
        7.2.11. Infrastructure for virtual packages
        7.2.12. Infrastructure for packages using kconfig for configuration
                files
        7.2.13. Hooks available in the various build steps
        7.2.14. Gettext integration and interaction with packages
        7.2.15. Tips and tricks
        7.2.16. Conclusion
    7.3. Patching a package
        7.3.1. Providing patches
        7.3.2. How patches are applied
        7.3.3. Format and licensing of the package patches
        7.3.4. Integrating patches found on the Web
    7.4. Download infrastructure
    7.5. Debugging Buildroot
8. Legal notice and licensing
    8.1. Complying with open source licenses
    8.2. License abbreviations
    8.3. Complying with the Buildroot license
9. Beyond Buildroot
    9.1. Boot the generated images
        9.1.1. NFS boot
    9.2. Chroot
10. Getting involved
    10.1. Mailing List
        10.1.1. Subscribing to the mailing list
        10.1.2. Searching the List Archives
    10.2. IRC
    10.3. Patchwork
        10.3.1. Applying Patches from Patchwork
    10.4. Bugtracker
    10.5. Buildroot wikipage
    10.6. Events
        10.6.1. Buildroot Developer Days aside ELC-E 2012 (November 3-4,
2012 - Barcelona)
        10.6.2. Buildroot presentation at LSM 2012 (July 12-14, 2012 -
                Geneva)
        10.6.3. Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012
                - Brussels)
11. Contributing to Buildroot
    11.1. Reproducing, analyzing and fixing bugs
    11.2. Analyzing and fixing autobuild failures
    11.3. Reviewing and testing patches
    11.4. Work on items from the TODO list
    11.5. Submitting patches
        11.5.1. Cover letter
        11.5.2. Patch revision changelog
    11.6. Reporting issues/bugs or getting help
12. Appendix
    12.1. Makedev syntax documentation
    12.2. Makeuser syntax documentation
    12.3. List of target packages available in Buildroot
    12.4. List of virtual packages
    12.5. List of host utilities available in Buildroot
    12.6. Deprecated features


and this patch converts it into:

I. Getting started
    1. About Buildroot
    2. System requirements
        2.1. Mandatory packages
        2.2. Optional packages
    3. Getting Buildroot
    4. Using Buildroot
II. User guide
    5. Details on Buildroot configuration
        5.1. Cross-compilation toolchain
        5.2. /dev management
        5.3. init system
    6. make tips
    7. Customization
        7.1. Customizing the generated target filesystem
        7.2. Customizing the BusyBox configuration
        7.3. Customizing the uClibc configuration
        7.4. Customizing the Linux kernel configuration
        7.5. Customizing the toolchain
    8. Storing the configuration
        8.1. Basics for storing the configuration
        8.2. Creating your own board support
        8.3. Step-by-step instructions for storing configuration
        8.4. Customizing packages
        8.5. Keeping customizations outside Buildroot
    9. Daily use
        9.1. Understanding when a full rebuild is necessary
        9.2. Understanding how to rebuild packages
        9.3. Offline builds
        9.4. Building out-of-tree
        9.5. Environment variables
        9.6. Dealing efficiently with filesystem images
        9.7. Graphing the dependencies between packages
        9.8. Graphing the build duration
    10. Integration with Eclipse
    11. Hacking Buildroot
    12. Frequently Asked Questions & Troubleshooting
        12.1. The boot hangs after Starting network?
        12.2. Why is there no compiler on the target?
        12.3. Why are there no development files on the target?
        12.4. Why is there no documentation on the target?
        12.5. Why are some packages not visible in the Buildroot config
              menu?
        12.6. Why not use the target directory as a chroot directory?
        12.7. Why doesn?t Buildroot generate binary packages (.deb, .ipkg?)?
    13. Known issues
    14. Going further in Buildroot?s innards
        14.1. How Buildroot works
        14.2. Advanced usage
    15. Legal notice and licensing
        15.1. Complying with open source licenses
        15.2. License abbreviations
        15.3. Complying with the Buildroot license
    16. Beyond Buildroot
        16.1. Boot the generated images
        16.2. Chroot
III. Developer guide
    17. Coding style
        17.1. Config.in file
        17.2. The .mk file
        17.3. The documentation
    18. Adding new packages to Buildroot
        18.1. Package directory
        18.2. Config.in file
        18.3. The .mk file
        18.4. The .hash file
        18.5. Infrastructure for packages with specific build systems
        18.6. Infrastructure for autotools-based packages
        18.7. Infrastructure for CMake-based packages
        18.8. Infrastructure for Python packages
        18.9. Infrastructure for LuaRocks-based packages
        18.10. Infrastructure for Perl/CPAN packages
        18.11. Infrastructure for virtual packages
        18.12. Infrastructure for packages using kconfig for configuration
               files
        18.13. Hooks available in the various build steps
        18.14. Gettext integration and interaction with packages
        18.15. Tips and tricks
        18.16. Conclusion
    19. Patching a package
        19.1. Providing patches
        19.2. How patches are applied
        19.3. Format and licensing of the package patches
        19.4. Integrating patches found on the Web
    20. Download infrastructure
    21. Debugging Buildroot
    22. Getting involved
        22.1. Mailing List
        22.2. IRC
        22.3. Patchwork
        22.4. Bugtracker
        22.5. Buildroot wikipage
        22.6. Events
    23. Contributing to Buildroot
        23.1. Reproducing, analyzing and fixing bugs
        23.2. Analyzing and fixing autobuild failures
        23.3. Reviewing and testing patches
        23.4. Work on items from the TODO list
        23.5. Submitting patches
        23.6. Reporting issues/bugs or getting help
IV. Appendix
    24. Makedev syntax documentation
    25. Makeuser syntax documentation
    26. List of target packages available in Buildroot
    27. List of virtual packages
    28. List of host utilities available in Buildroot
    29. Deprecated features

diff -r a33a76437a5c -r 00ad338df278 docs/manual/advanced.txt
--- a/docs/manual/advanced.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/advanced.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-== Advanced usage
+=== Advanced usage
 
 include::using-buildroot-toolchain.txt[]
 
diff -r a33a76437a5c -r 00ad338df278 docs/manual/appendix.txt
--- a/docs/manual/appendix.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/appendix.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,8 +1,6 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Appendix
-
 include::makedev-syntax.txt[]
 include::makeusers-syntax.txt[]
 
diff -r a33a76437a5c -r 00ad338df278 docs/manual/beyond-buildroot.txt
--- a/docs/manual/beyond-buildroot.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/beyond-buildroot.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,11 +1,11 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Beyond Buildroot
+== Beyond Buildroot
 
-== Boot the generated images
+=== Boot the generated images
 
-=== NFS boot
+==== NFS boot
 
 To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem
 images_ menu.
@@ -21,7 +21,7 @@
 
 Then, you can execute a NFS-boot from your target.
 
-== Chroot
+=== Chroot
 
 If you want to chroot in a generated image, then there are few thing
 you should be aware of:
diff -r a33a76437a5c -r 00ad338df278 docs/manual/ccache-support.txt
--- a/docs/manual/ccache-support.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/ccache-support.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -2,7 +2,7 @@
 // vim: set syntax=asciidoc:
 
 [[ccache]]
-=== Using +ccache+ in Buildroot
+==== Using +ccache+ in Buildroot
 
 http://ccache.samba.org[ccache] is a compiler cache. It stores the
 object files resulting from each compilation process, and is able to
diff -r a33a76437a5c -r 00ad338df278 docs/manual/contribute.txt
--- a/docs/manual/contribute.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/contribute.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Contributing to Buildroot
+== Contributing to Buildroot
 
 There are many ways in which you can contribute to Buildroot: analyzing
 and fixing bugs, analyzing and fixing package build failures detected by
@@ -22,7 +22,7 @@
 send your patches to the mailing list. Refer to xref:getting-buildroot[]
 for more information on obtaining a Buildroot git tree.
 
-== Reproducing, analyzing and fixing bugs
+=== Reproducing, analyzing and fixing bugs
 
 A first way of contributing is to have a look at the open bug reports in
 the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot bug
@@ -31,7 +31,7 @@
 welcome. Don't hesitate to add a comment to bug reports reporting your
 findings, even if you don't yet see the full picture.
 
-== Analyzing and fixing autobuild failures
+=== Analyzing and fixing autobuild failures
 
 The Buildroot autobuilders are a set of build machines that continuously
 run Buildroot builds based on random configurations. This is done for
@@ -76,7 +76,7 @@
 Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
 ---------------------
 
-== Reviewing and testing patches
+=== Reviewing and testing patches
 
 With the amount of patches sent to the mailing list each day, the
 maintainer has a very hard job to judge which patches are ready to apply
@@ -142,7 +142,7 @@
 purposes. Please see xref:apply-patches-patchwork[] for more
 information on using Buildroot's Patchwork website to apply patches.
 
-== Work on items from the TODO list
+=== Work on items from the TODO list
 
 If you want to contribute to Buildroot but don't know where to start,
 and you don't like any of the above topics, you can always work on items
@@ -152,7 +152,7 @@
 avoid duplicate efforts.
 
 [[submitting-patches]]
-== Submitting patches
+=== Submitting patches
 
 [NOTE]
 _Please, do not attach patches to bugs, send them to the mailing list
@@ -196,7 +196,7 @@
 line-wrapped*, otherwise they cannot easily be applied. In such a case,
 fix your e-mail client, or better yet, learn to use +git send-email+.
 
-=== Cover letter
+==== 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
@@ -215,7 +215,7 @@
 * whenever you feel it will help presenting your work, your choices,
   the review process, etc.
 
-=== Patch revision changelog
+==== Patch revision changelog
 
 When improvements are requested, the new revision of each commit
 should include a changelog of the modifications between each
@@ -276,7 +276,7 @@
 ---------------------
 
 [[reporting-bugs]]
-== Reporting issues/bugs or getting help
+=== Reporting issues/bugs or getting help
 
 Before reporting any issue, please check
 xref:mailing-list-subscribe[the mailing list archive] in case someone has
diff -r a33a76437a5c -r 00ad338df278 docs/manual/developer-guide.txt
--- a/docs/manual/developer-guide.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/developer-guide.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,8 +1,6 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Developer Guidelines
-
 include::writing-rules.txt[]
 
 include::adding-packages.txt[]
diff -r a33a76437a5c -r 00ad338df278 docs/manual/download-location.txt
--- a/docs/manual/download-location.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/download-location.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-=== Location of downloaded packages
+==== Location of downloaded packages
 
 The various tarballs that are downloaded by Buildroot are all stored
 in +BR2_DL_DIR+, which by default is the +dl+ directory. If you want
diff -r a33a76437a5c -r 00ad338df278 docs/manual/faq-troubleshooting.txt
--- a/docs/manual/faq-troubleshooting.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/faq-troubleshooting.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,10 +1,10 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Frequently Asked Questions & Troubleshooting
+== Frequently Asked Questions & Troubleshooting
 
 [[faq-boot-hang-after-starting]]
-== The boot hangs after 'Starting network...'
+=== The boot hangs after 'Starting network...'
 
 If the boot process seems to hang after the following messages
 (messages not necessarily exactly similar, depending on the list of
@@ -26,7 +26,7 @@
 generated system so that a shell starts on the correct serial port.
 
 [[faq-no-compiler-on-target]]
-== Why is there no compiler on the target?
+=== Why is there no compiler on the target?
 
 It has been decided that support for the _native compiler on the
 target_ would be stopped from the Buildroot-2012.11 release because:
@@ -50,7 +50,7 @@
 * ...
 
 [[faq-no-dev-files-on-target]]
-== Why are there no development files on the target?
+=== Why are there no development files on the target?
 
 Since there is no compiler available on the target (see
 xref:faq-no-compiler-on-target[]), it does not make sense to waste
@@ -60,7 +60,7 @@
 Buildroot-2012.11 release.
 
 [[faq-no-doc-on-target]]
-== Why is there no documentation on the target?
+=== Why is there no documentation on the target?
 
 Because Buildroot mostly targets _small_ or _very small_ target
 hardware with limited resource onboard (CPU, ram, mass-storage), it
@@ -71,7 +71,7 @@
 distribution_ (see: xref:faq-no-compiler-on-target[]).
 
 [[faq-why-not-visible-package]]
-== Why are some packages not visible in the Buildroot config menu?
+=== Why are some packages not visible in the Buildroot config menu?
 
 If a package exists in the Buildroot tree and does not appear in the
 config menu, this most likely means that some of the package's
@@ -89,7 +89,7 @@
 more explanations).
 
 [[faq-why-not-use-target-as-chroot]]
-== Why not use the target directory as a chroot directory?
+=== Why not use the target directory as a chroot directory?
 
 There are plenty of reasons to *not* use the target directory a chroot
 one, among these:
@@ -106,7 +106,7 @@
 as root.
 
 [[faq-no-binary-packages]]
-== Why doesn't Buildroot generate binary packages (.deb, .ipkg...)?
+=== Why doesn't Buildroot generate binary packages (.deb, .ipkg...)?
 
 One feature that is often discussed on the Buildroot list is the
 general topic of "package management". To summarize, the idea
diff -r a33a76437a5c -r 00ad338df278 docs/manual/get-involved.txt
--- a/docs/manual/get-involved.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/get-involved.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Getting involved
+== Getting involved
 
 Like any open source project, Buildroot has different ways to share
 information in its community and outside.
@@ -11,7 +11,7 @@
 Each of those ways may interest you if you are looking for some help,
 want to understand Buildroot or contribute to the project.
 
-== Mailing List
+=== Mailing List
 
 Buildroot has a mailing list
 http://lists.busybox.net/pipermail/buildroot[] for discussion and
@@ -19,7 +19,7 @@
 
 [[mailing-list-subscribe]]
 
-=== Subscribing to the mailing list
+==== Subscribing to the mailing list
 
 You can subscribe by visiting
 http://lists.busybox.net/mailman/listinfo/buildroot[].
@@ -30,14 +30,14 @@
 +gmane.comp.lib.uclibc.buildroot+
 http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[].
 
-=== Searching the List Archives
+==== Searching the List Archives
 
 Please search the mailing list archives before asking questions on the
 mailing list, since there is a good chance someone else has asked the
 same question before. Checking the archives is a great way to avoid
 annoying everyone on the list with frequently asked questions...
 
-== IRC
+=== IRC
 
 The Buildroot IRC is irc://freenode.net/#buildroot[].
 The channel +#buildroot+ is hosted on Freenode
@@ -47,7 +47,7 @@
 using a code sharing website.
 
 [[patchwork]]
-== Patchwork
+=== Patchwork
 
 Patchwork is a web-based patch tracking system designed to facilitate
 the contribution and management of contributions to an open-source
@@ -66,7 +66,7 @@
 http://patchwork.buildroot.org[].
 
 [[apply-patches-patchwork]]
-=== Applying Patches from Patchwork
+==== Applying Patches from Patchwork
 
 The main use of Buildroot's Patchwork website for a developer is for
 pulling in patches into their local git repository for testing
@@ -88,13 +88,13 @@
 using the above commands.
 
 [[bugtracker]]
-== Bugtracker
+=== Bugtracker
 
 The Buildroot bugtracker is at https://bugs.busybox.net[].
 
 To open a bug, see xref:reporting-bugs[].
 
-== Buildroot wikipage
+=== Buildroot wikipage
 
 After the Buildroot developer day on February 3, 2012,
 a page dedicated to Buildroot has been created on
@@ -105,17 +105,17 @@
 Currently, this page is mainly used as a _todo-list_.
 
 [[events]]
-== Events
+=== Events
 
-=== Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona)
+==== Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona)
 
 * Event page: http://elinux.org/Buildroot:DeveloperDaysELCE2012[]
 
-=== Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva)
+==== Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva)
 
 * Announcement: http://lists.busybox.net/pipermail/buildroot/2012-May/053845.html[]
 
-=== Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
+==== Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
 
 * Announcement & agenda thread: http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
 * Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]
diff -r a33a76437a5c -r 00ad338df278 docs/manual/going-further.txt
--- a/docs/manual/going-further.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/going-further.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Going further in Buildroot's innards
+== Going further in Buildroot's innards
 
 include::how-buildroot-works.txt[]
 
diff -r a33a76437a5c -r 00ad338df278 docs/manual/how-buildroot-works.txt
--- a/docs/manual/how-buildroot-works.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/how-buildroot-works.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-== How Buildroot works
+=== How Buildroot works
 
 As mentioned above, Buildroot is basically a set of Makefiles that
 download, configure, and compile software with the correct options. It
diff -r a33a76437a5c -r 00ad338df278 docs/manual/introduction.txt
--- a/docs/manual/introduction.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/introduction.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= About Buildroot
+== About Buildroot
 
 Buildroot is a tool that simplifies and automates the process of
 building a complete Linux system for an embedded system, using
diff -r a33a76437a5c -r 00ad338df278 docs/manual/known-issues.txt
--- a/docs/manual/known-issues.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/known-issues.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Known issues
+== Known issues
 
 * It is not possible to pass extra linker options via +BR2_TARGET_LDFLAGS+
   if such options contain a +$+ sign. For example, the following is known
diff -r a33a76437a5c -r 00ad338df278 docs/manual/legal-notice.txt
--- a/docs/manual/legal-notice.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/legal-notice.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -3,9 +3,9 @@
 
 [[legal-info]]
 
-= Legal notice and licensing
+== Legal notice and licensing
 
-== Complying with open source licenses
+=== Complying with open source licenses
 
 All of the end products of Buildroot (toolchain, root filesystem, kernel,
 bootloaders) contain open source software, released under various licenses.
@@ -69,7 +69,7 @@
 file to inform you of relevant material that could not be saved.
 
 [[legal-info-list-licenses]]
-== License abbreviations
+=== License abbreviations
 
 Here is a list of the licenses that are most widely used by packages in
 Buildroot, with the name used in the manifest files:
@@ -123,7 +123,7 @@
   http://apache.org/licenses/LICENSE-2.0.html[
   Apache License, version 2.0];
 
-== Complying with the Buildroot license
+=== Complying with the Buildroot license
 
 Buildroot itself is an open source software, released under the
 http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU General Public
diff -r a33a76437a5c -r 00ad338df278 docs/manual/manual.mk
--- a/docs/manual/manual.mk	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/manual.mk	Wed Aug 06 19:48:39 2014 +0200
@@ -83,8 +83,8 @@
 # The variable <DOCUMENT_NAME>_SOURCES defines the dependencies.
 ################################################################################
 define GENDOC
-$(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,--xsltproc-opts "--stringparam toc.section.depth 2")
-$(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,--xsltproc-opts "--stringparam toc.section.depth 2")
+$(call GENDOC_INNER,$(pkgname),xhtml,html,html,HTML,--xsltproc-opts "--stringparam toc.section.depth 1")
+$(call GENDOC_INNER,$(pkgname),chunked,split-html,chunked,split HTML,--xsltproc-opts "--stringparam toc.section.depth 1")
 $(call GENDOC_INNER,$(pkgname),pdf,pdf,pdf,PDF,--dblatex-opts "-P latex.output.revhistory=0")
 $(call GENDOC_INNER,$(pkgname),text,text,text,text)
 $(call GENDOC_INNER,$(pkgname),epub,epub,epub,ePUB)
diff -r a33a76437a5c -r 00ad338df278 docs/manual/manual.txt
--- a/docs/manual/manual.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/manual.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -16,12 +16,14 @@
 
 image::logo.png[]
 
-:leveloffset: 1
+= Getting started
 
 include::introduction.txt[]
 
 include::starting-up.txt[]
 
+= User guide
+
 include::working-with.txt[]
 
 include::faq-troubleshooting.txt[]
@@ -30,14 +32,18 @@
 
 include::going-further.txt[]
 
-include::developer-guide.txt[]
-
 include::legal-notice.txt[]
 
 include::beyond-buildroot.txt[]
 
+= Developer guide
+
+include::developer-guide.txt[]
+
 include::get-involved.txt[]
 
 include::contribute.txt[]
 
+= Appendix
+
 include::appendix.txt[]
diff -r a33a76437a5c -r 00ad338df278 docs/manual/package-make-target.txt
--- a/docs/manual/package-make-target.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/package-make-target.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -3,7 +3,7 @@
 
 [[pkg-build-steps]]
 
-=== Package-specific _make_ targets
+==== Package-specific _make_ targets
 
 Running +make <package>+ builds and installs that particular package
 and its dependencies.
diff -r a33a76437a5c -r 00ad338df278 docs/manual/starting-up.txt
--- a/docs/manual/starting-up.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/starting-up.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,8 +1,6 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Starting up
-
 include::prerequisite.txt[]
 
 include::getting.txt[]
diff -r a33a76437a5c -r 00ad338df278 docs/manual/using-buildroot-debugger.txt
--- a/docs/manual/using-buildroot-debugger.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/using-buildroot-debugger.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-=== Using +gdb+ in Buildroot
+==== Using +gdb+ in Buildroot
 
 Buildroot allows to do cross-debugging, where the debugger runs on the
 build machine and communicates with +gdbserver+ on the target to
diff -r a33a76437a5c -r 00ad338df278 docs/manual/using-buildroot-development.txt
--- a/docs/manual/using-buildroot-development.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/using-buildroot-development.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-=== Using Buildroot during development
+==== Using Buildroot during development
 
 The normal operation of Buildroot is to download a tarball, extract
 it, configure, compile and install the software component found inside
diff -r a33a76437a5c -r 00ad338df278 docs/manual/using-buildroot-toolchain.txt
--- a/docs/manual/using-buildroot-toolchain.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/using-buildroot-toolchain.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-=== Using the generated toolchain outside Buildroot
+==== Using the generated toolchain outside Buildroot
 
 You may want to compile, for your target, your own programs or other
 software that are not packaged in Buildroot. In order to do this you
diff -r a33a76437a5c -r 00ad338df278 docs/manual/working-with.txt
--- a/docs/manual/working-with.txt	Sun Aug 10 17:55:54 2014 +0200
+++ b/docs/manual/working-with.txt	Wed Aug 06 19:48:39 2014 +0200
@@ -1,8 +1,6 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-= Working with Buildroot
-
 This section explains how you can customize Buildroot to fit your
 needs.
 

[Buildroot] [PATCH 2 of 8 RFCv2 for 2014.08] manual: remove 'Events' section

[Thomas De Schampheleire]

The list of buildroot events is outdated, a sign that the manual is not the
best place to refer to timely things like events. The wiki page is better
suited for such information.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/get-involved.txt |  16 ----------------
 1 files changed, 0 insertions(+), 16 deletions(-)

diff -r 00ad338df278 -r 384a21645bf2 docs/manual/get-involved.txt
--- a/docs/manual/get-involved.txt	Wed Aug 06 19:48:39 2014 +0200
+++ b/docs/manual/get-involved.txt	Wed Aug 06 20:28:19 2014 +0200
@@ -103,19 +103,3 @@
 This page is reachable at http://elinux.org/Buildroot[].
 
 Currently, this page is mainly used as a _todo-list_.
-
-[[events]]
-=== Events
-
-==== Buildroot Developer Days aside ELC-E 2012 (November 3-4, 2012 - Barcelona)
-
-* Event page: http://elinux.org/Buildroot:DeveloperDaysELCE2012[]
-
-==== Buildroot presentation at LSM 2012 (July 12-14, 2012 - Geneva)
-
-* Announcement: http://lists.busybox.net/pipermail/buildroot/2012-May/053845.html[]
-
-==== Buildroot Developer Days aside FOSDEM 2012 (February 3, 2012 - Brussels)
-
-* Announcement & agenda thread: http://lists.busybox.net/pipermail/buildroot/2012-January/049340.html[]
-* Report: http://lists.busybox.net/pipermail/buildroot/2012-February/050371.html[]

[Buildroot] [PATCH 3 of 8 RFCv2 for 2014.08] manual/getting started: rename and move 'Getting involved' section

[Thomas De Schampheleire]

The Getting Involved section is actually an overview of the ways to interact
with the Buildroot community, which is useful for developers _and_ users.
Therefore, this patch moves the section from the Developer Guide to the
Getting Started section, and renames it to 'Community Resources'.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
Note: I'm open to other names than 'Community Resources'

 docs/manual/get-involved.txt |  2 +-
 docs/manual/manual.txt       |  4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff -r 384a21645bf2 -r c55bf02ff149 docs/manual/get-involved.txt
--- a/docs/manual/get-involved.txt	Wed Aug 06 20:28:19 2014 +0200
+++ b/docs/manual/get-involved.txt	Thu Aug 07 18:05:13 2014 +0200
@@ -1,7 +1,7 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-== Getting involved
+== Community resources
 
 Like any open source project, Buildroot has different ways to share
 information in its community and outside.
diff -r 384a21645bf2 -r c55bf02ff149 docs/manual/manual.txt
--- a/docs/manual/manual.txt	Wed Aug 06 20:28:19 2014 +0200
+++ b/docs/manual/manual.txt	Thu Aug 07 18:05:13 2014 +0200
@@ -22,6 +22,8 @@
 
 include::starting-up.txt[]
 
+include::get-involved.txt[]
+
 = User guide
 
 include::working-with.txt[]
@@ -40,8 +42,6 @@
 
 include::developer-guide.txt[]
 
-include::get-involved.txt[]
-
 include::contribute.txt[]
 
 = Appendix

[Buildroot] [PATCH 4 of 8 RFCv2 for 2014.08] manual/getting started: rework 'Community resources' section

[Thomas De Schampheleire]

This patch reworks the section 'Community resources' as follows:
- use a labeled list instead of subsections, as the content of each section
  is so small that it does not deserve a real section.
  Related to this, the anchors for each of these subsections are removed, as
  referencing such anchors that do not correspond to a section boundary are
  not displayed nicely.
- move the part about applying patches from patchwork to the Contributing
  section in the Developer Guide
- reword some parts of the text
- add link texts to some links, instead of showing the URL directly, to make
  the HTML / PDF display nicer.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt   |   35 +++++++-
 docs/manual/get-involved.txt |  128 +++++++++++++---------------------
 2 files changed, 77 insertions(+), 86 deletions(-)

diff -r c55bf02ff149 -r 2f17e63e3fec docs/manual/contribute.txt
--- a/docs/manual/contribute.txt	Thu Aug 07 18:05:13 2014 +0200
+++ b/docs/manual/contribute.txt	Thu Aug 07 18:10:10 2014 +0200
@@ -14,7 +14,7 @@
 should do is to subscribe to the Buildroot mailing list. This list is
 the main way of interacting with other Buildroot developers and to send
 contributions to. If you aren't subscribed yet, then refer to
-xref:mailing-list-subscribe[].
+xref:community-resources[] for the subscription link.
 
 If you are going to touch the code, it is highly recommended to use a
 git repository of Buildroot, rather than starting from an extracted
@@ -142,6 +142,29 @@
 purposes. Please see xref:apply-patches-patchwork[] for more
 information on using Buildroot's Patchwork website to apply patches.
 
+[[apply-patches-patchwork]]
+==== Applying Patches from Patchwork
+
+The main use of Buildroot's Patchwork website for a developer is for
+pulling in patches into their local git repository for testing
+purposes.
+
+When browsing patches in the patchwork management interface, an +mbox+
+link is provided at the top of the page. Copy this link address and
+run the following commands:
+
+---------------------
+$ git checkout -b <test-branch-name>
+$ wget -O - <mbox-url> | git am
+---------------------
+
+Another option for applying patches is to create a bundle. A bundle is
+a set of patches that you can group together using the patchwork
+interface. Once the bundle is created and the bundle is made public,
+you can copy the +mbox+ link for the bundle and apply the bundle
+using the above commands.
+
+
 === Work on items from the TODO list
 
 If you want to contribute to Buildroot but don't know where to start,
@@ -278,13 +301,13 @@
 [[reporting-bugs]]
 === Reporting issues/bugs or getting help
 
-Before reporting any issue, please check
-xref:mailing-list-subscribe[the mailing list archive] in case someone has
-already reported and fixed a similar problem.
+Before reporting any issue, please check in
+xref:community-resources[the mailing list archive] whether someone has
+already reported and/or fixed a similar problem.
 
 However you choose to report bugs or get help, either by
-xref:bugtracker[opening a bug] or by
-xref:mailing-list-subscribe[sending a mail to the mailing list], there are
+opening a bug in the xref:community-resources[bug tracker] or by
+xref:community-resources[sending a mail to the mailing list], there are
 a number of details to provide in order to help people reproduce and
 find a solution to the issue.
 
diff -r c55bf02ff149 -r 2f17e63e3fec docs/manual/get-involved.txt
--- a/docs/manual/get-involved.txt	Thu Aug 07 18:05:13 2014 +0200
+++ b/docs/manual/get-involved.txt	Thu Aug 07 18:10:10 2014 +0200
@@ -1,54 +1,59 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
+[[community-resources]]
 == Community resources
 
 Like any open source project, Buildroot has different ways to share
 information in its community and outside.
 
-One piece of it is the document you are currently reading ;-).
-
 Each of those ways may interest you if you are looking for some help,
 want to understand Buildroot or contribute to the project.
 
-=== Mailing List
+Mailing List::
++
+Buildroot has a mailing list for discussion and development. It is the
+main method of interaction for Buildroot users and developers.
++
+Only subscribers to the Buildroot mailing list are allowed to post to
+this list. You can subscribe via the
+http://lists.busybox.net/mailman/listinfo/buildroot[mailing list info
+page].
++
+Mails that are sent to the mailing list are also available in the
+http://lists.busybox.net/pipermail/buildroot[mailing list archives] and
+via http://gmane.org[Gmane], at
+http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[+gmane.comp.lib.uclibc.buildroot+].
+Please search the mailing list archives before asking questions, since
+there is a good chance someone else has asked the same question before.
 
-Buildroot has a mailing list
-http://lists.busybox.net/pipermail/buildroot[] for discussion and
-development.
+IRC::
++
+The Buildroot IRC channel irc://freenode.net/#buildroot[#buildroot] is
+hosted on http://webchat.freenode.net[Freenode]. It is a useful place to
+ask quick questions or discuss on certain topics.
++
+When asking for help on IRC, share relevant logs or pieces of code
+using a code sharing website, such as http://code.bulix.org.
++
+Note that for certain questions, posting to the mailing list may be
+better as it will reach more people, both developers and users.
 
-[[mailing-list-subscribe]]
+Bug tracker::
++
+Bugs in Buildroot can be reported via the mailing list or alternatively
+via the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot
+bugtracker]. Please refer to xref:reporting-bugs[] before creating a bug
+report.
 
-==== Subscribing to the mailing list
+Wiki::
++
+http://elinux.org/Buildroot[The Buildroot wiki page] is hosted on
+the http://elinux.org[eLinux] wiki. It contains some useful links, an
+overview of past and upcoming events, and a TODO list.
 
-You can subscribe by visiting
-http://lists.busybox.net/mailman/listinfo/buildroot[].
-Only subscribers to the Buildroot mailing list are allowed to post to
-this list.
-
-The list is also available through _Gmane_ http://gmane.org[], at
-+gmane.comp.lib.uclibc.buildroot+
-http://dir.gmane.org/gmane.comp.lib.uclibc.buildroot[].
-
-==== Searching the List Archives
-
-Please search the mailing list archives before asking questions on the
-mailing list, since there is a good chance someone else has asked the
-same question before. Checking the archives is a great way to avoid
-annoying everyone on the list with frequently asked questions...
-
-=== IRC
-
-The Buildroot IRC is irc://freenode.net/#buildroot[].
-The channel +#buildroot+ is hosted on Freenode
-http://webchat.freenode.net[].
-
-When asking for help on IRC, share relevant logs or pieces of code
-using a code sharing website.
-
-[[patchwork]]
-=== Patchwork
-
+Patchwork::
++
 Patchwork is a web-based patch tracking system designed to facilitate
 the contribution and management of contributions to an open-source
 project. Patches that have been sent to a mailing list are \'caught' by
@@ -56,50 +61,13 @@
 reference the patch are appended to the patch page too. For more
 information on Patchwork see
 http://jk.ozlabs.org/projects/patchwork[].
-
++
 Buildroot's Patchwork website is mainly for use by Buildroot's
-maintainer to ensure patches aren't missed. The website however,
-exposes patches and their corresponding review comments in a clean
-and concise web interface.
-
+maintainer to ensure patches aren't missed. It is also used by Buildroot
+patch reviewers (see also xref:apply-patches-patchwork[]).
+However, since the website exposes patches and their corresponding
+review comments in a clean and concise web interface, it can be useful
+for all Buildroot developers.
++
 The Buildroot patch management interface is available at
 http://patchwork.buildroot.org[].
-
-[[apply-patches-patchwork]]
-==== Applying Patches from Patchwork
-
-The main use of Buildroot's Patchwork website for a developer is for
-pulling in patches into their local git repository for testing
-purposes.
-
-When browsing patches in the patchwork management interface, an +mbox+
-link is provided at the top of the page. Copy this link address and
-run the following commands:
-
----------------------
-$ git checkout -b <test-branch-name>
-$ wget -O - <mbox-url> | git am
----------------------
-
-Another option for applying patches is to create a bundle. A bundle is
-a set of patches that you can group together using the patchwork
-interface. Once the bundle is created and the bundle is made public,
-you can copy the +mbox+ link for the bundle and apply the bundle
-using the above commands.
-
-[[bugtracker]]
-=== Bugtracker
-
-The Buildroot bugtracker is at https://bugs.busybox.net[].
-
-To open a bug, see xref:reporting-bugs[].
-
-=== Buildroot wikipage
-
-After the Buildroot developer day on February 3, 2012,
-a page dedicated to Buildroot has been created on
-http://elinux.org[elinux.org].
-
-This page is reachable at http://elinux.org/Buildroot[].
-
-Currently, this page is mainly used as a _todo-list_.

[Buildroot] [PATCH 5 of 8 RFCv2 for 2014.08] manual/getting started: rework 'System requirements' section

[Thomas De Schampheleire]

This patch reworks the requirements section of the manual as follows:
- some general rewording
- move configuration editor dependencies above the download tools, as this
  is the first thing people come in contact with.
- move sentence regarding -dev packages to configuration editor dependencies
  and restrict to 'libraries'.
- clarify the download tools part.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/prerequisite.txt |  40 +++++++++++++++++++----------------
 1 files changed, 22 insertions(+), 18 deletions(-)

diff -r 2f17e63e3fec -r dd6d42a03816 docs/manual/prerequisite.txt
--- a/docs/manual/prerequisite.txt	Thu Aug 07 18:10:10 2014 +0200
+++ b/docs/manual/prerequisite.txt	Tue Aug 12 20:09:13 2014 +0200
@@ -6,13 +6,11 @@
 
 Buildroot is designed to run on Linux systems.
 
-Buildroot needs some software to be already installed on the host
-system; here are the lists of the mandatory and optional packages
-(package names may vary between distributions).
-
-Take care to _install both runtime and development data_, especially
-for the libraries that may be packaged in 2 distinct packages.
-
+While Buildroot itself will build most host packages it needs for the
+compilation, certain standard Linux utilities are expected to be
+already installed on the host system. Below you will find an overview of
+the mandatory and optional packages (note that package names may vary
+between distributions).
 
 [[requirement-mandatory]]
 
@@ -45,14 +43,25 @@
 
 === Optional packages
 
+* Configuration interface dependencies:
++
+For these libraries, you need to install both runtime and development
+data, which in many distributions are packaged separately. The
+development packages typically have a _-dev_ or _-devel_ suffix.
++
+** +ncurses5+ to use the 'menuconfig' interface
+** +qt4+ to use the 'xconfig' interface
+** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
+
 * Source fetching tools:
 +
-In the official tree, most of the package sources are retrieved
-using +wget+; a few are only available through their +git+, +mercurial+,
-+svn+ or +cvs+ repository.
-+
-All other source fetching methods are implemented and may be used in a
-development context (further details: refer to xref:download-infra[]).
+In the official tree, most of the package sources are retrieved using
++wget+ from _ftp_, _http_ or _https_ locations. A few packages are only
+available through a version control system. Moreover, Buildroot is
+capable of downloading sources via other tools, like +rsync+ or +scp+
+(refer to xref:download-infra[] for more details). If you enable
+packages using any of these methods, you will need to install the
+corresponding tool on the host system:
 +
 ** +bazaar+
 ** +cvs+
@@ -62,11 +71,6 @@
 ** +scp+
 ** +subversion+
 
-* Configuration interface dependencies (requires development libraries):
-** +ncurses5+ to use the 'menuconfig' interface
-** +qt4+ to use the 'xconfig' interface
-** +glib2+, +gtk2+ and +glade2+ to use the 'gconfig' interface
-
 * Java-related packages, if the Java Classpath needs to be built for
   the target system:
 ** The +javac+ compiler

[Buildroot] [PATCH 6 of 8 RFCv2 for 2014.08] website/download: update daily snapshot section

[Thomas De Schampheleire]

This patch makes some minor changes to the download page of the website:
- don't capitalize Daily Snapshots as there is no reason to.
- remove extra link to daily snapshots, as this link is already available on
  the line below.
- add a link to the latest snapshot
- avoid 'Click here', especially if 'here' is not clickable

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/download.html |  13 +++++++------
 1 files changed, 7 insertions(+), 6 deletions(-)

diff -r dd6d42a03816 -r 093e0ba716de docs/download.html
--- a/docs/download.html	Tue Aug 12 20:09:13 2014 +0200
+++ b/docs/download.html	Tue Aug 12 21:34:32 2014 +0200
@@ -30,17 +30,18 @@
 
 <p>
 
-You can also obtain <a href="/downloads/snapshots/">Daily
-Snapshots</a> of the latest Buildroot source tree if you want to to
-follow development, but cannot or do not wish to use Git.
+You can also obtain daily snapshots of the latest Buildroot source tree if you
+want to follow development, but cannot or do not wish to use Git.
 
 <ul>
-	<li> Click here to <a href="downloads/snapshots/">Daily Snapshots</a>.
+	<li>You can download the
+	<a href="downloads/snapshots/buildroot-snapshot.tar.bz2">latest snapshot
+	</a> or view recent <a href="downloads/snapshots/">daily snapshots</a>.
 	</li>
 
-	<li> Click here to <a href="http://git.buildroot.net/buildroot">browse the source tree</a>.
+	<li>You can also <a href="http://git.buildroot.net/buildroot">browse the
+	source tree online</a>.
 	</li>
-
 </ul>
 
 

[Buildroot] [PATCH 7 of 8 RFCv2 for 2014.08] manual/getting started: rework 'Getting Buildroot' section

[Thomas De Schampheleire]

This patch reworks the 'Getting Buildroot' section of the manual as follows:
- be more specific on the Buildroot release cycle
- refer to the download page of the website for details on snapshots and
  git, instead of duplicating the information.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/getting.txt |  26 ++++++++------------------
 1 files changed, 8 insertions(+), 18 deletions(-)

diff -r 093e0ba716de -r 770cb501d536 docs/manual/getting.txt
--- a/docs/manual/getting.txt	Tue Aug 12 21:34:32 2014 +0200
+++ b/docs/manual/getting.txt	Tue Aug 12 21:11:54 2014 +0200
@@ -4,23 +4,13 @@
 [[getting-buildroot]]
 == Getting Buildroot
 
-Buildroot releases are made approximately every 3 months. Direct Git
-access and daily snapshots are also available, if you want more
-bleeding edge.
+Buildroot releases are made every 3 months, in February, May, August and
+November. Release numbers are in the format YYYY.MM, so for example
+2013.02, 2014.08.
 
-Releases are available at http://buildroot.net/downloads/[].
+Release tarballs are available at http://buildroot.org/downloads/[].
 
-The latest snapshot is always available at
-http://buildroot.net/downloads/snapshots/buildroot-snapshot.tar.bz2[],
-and previous snapshots are also available at
-http://buildroot.net/downloads/snapshots/[].
-
-To download Buildroot using Git, you can simply follow the rules
-described on the "Accessing Git" page
-(http://buildroot.net/git.html[]) of the Buildroot website
-(http://buildroot.net[]).  For the impatient, here's a quick recipe:
-
----------------------
- $ git clone git://git.buildroot.net/buildroot
----------------------
-
+If you want to follow development, you can use the daily snapshots or
+make a clone of the Git repository. Refer to the
+http://buildroot.org/download[Download page] of the Buildroot website
+for more details.

[Buildroot] [PATCH 8 of 8 RFCv2 for 2014.08] manual/getting started: rework 'Using Buildroot' section

[Thomas De Schampheleire]

This patch does some general rewording of the 'Using buildroot' section
of the manual.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/using.txt |  59 ++++++++++++++++++++++++------------------
 1 files changed, 33 insertions(+), 26 deletions(-)

diff -r 770cb501d536 -r f7d6a73e756a docs/manual/using.txt
--- a/docs/manual/using.txt	Tue Aug 12 21:11:54 2014 +0200
+++ b/docs/manual/using.txt	Tue Aug 12 22:14:07 2014 +0200
@@ -3,67 +3,73 @@
 
 == Using Buildroot
 
+*Important*: you can and should *build everything as a normal user*. There
+is no need to be root to configure and use Buildroot. By running all
+commands as a regular user, you protect your system against packages
+behaving badly during compilation and installation.
+
+The first step when using Buildroot is to create a configuration.
 Buildroot has a nice configuration tool similar to the one you can
 find in the http://www.kernel.org/[Linux kernel] or in
-http://www.busybox.net/[BusyBox]. Note that you can *and should build
-everything as a normal user*. There is no need to be root to configure
-and use Buildroot. The first step is to run the configuration
-assistant:
+http://www.busybox.net/[BusyBox].
+
+From the buildroot directory, run
 
 --------------------
  $ make menuconfig
 --------------------
 
-or
+for the original curses-based configurator, or
 
 --------------------
  $ make nconfig
 --------------------
 
-to run the old or new curses-based configurator, or
+for the new curses-based configurator, or
 
 --------------------
  $ make xconfig
 --------------------
 
-or
+for the Qt-based configurator, or
 
 --------------------
  $ make gconfig
 --------------------
 
-to run the Qt or GTK-based configurators.
+for the GTK-based configurator.
 
 All of these "make" commands will need to build a configuration
 utility (including the interface), so you may need to install
 "development" packages for relevant libraries used by the
-configuration utilities. Check xref:requirement[] to know what
-Buildroot needs, and specifically the xref:requirement-optional[optional requirements]
+configuration utilities. Refer to xref:requirement[] for more details,
+specifically the xref:requirement-optional[optional requirements]
 to get the dependencies of your favorite interface.
 
 For each menu entry in the configuration tool, you can find associated
 help that describes the purpose of the entry.
 
 Once everything is configured, the configuration tool generates a
-+.config+ file that contains the description of your
-configuration. It will be used by the Makefiles to do what's needed.
++.config+ file that contains the entire configuration. This file will be
+read by the top-level Makefile.
 
-Let's go:
+To start the build process, simply run:
 
 --------------------
  $ make
 --------------------
 
-You *should never* use +make -jN+ with Buildroot: it does not support
-'top-level parallel make'. Instead, use the +BR2_JLEVEL+ option to
-tell Buildroot to run each package compilation with +make -jN+.
+You *should never* use +make -jN+ with Buildroot: top-level parallel
+make is currently not supported. Instead, use the +BR2_JLEVEL+ option
+to tell Buildroot to run the compilation of each individual package
+with +make -jN+.
 
 The `make` command will generally perform the following steps:
 
 * download source files (as required);
-* configure, build and install the cross-compiling toolchain using the
-  appropriate toolchain backend, or simply import an external toolchain;
-* build/install selected target packages;
+* configure, build and install the cross-compilation toolchain, or
+  simply import an external toolchain;
+* configure, build and install selected target packages;
 * build a kernel image, if selected;
 * build a bootloader image, if selected;
 * create a root filesystem in selected formats.
@@ -72,15 +78,16 @@
 This directory contains several subdirectories:
 
 * +images/+ where all the images (kernel image, bootloader and root
-  filesystem images) are stored.
+  filesystem images) are stored. These are the files you need to put
+  on your target system.
 
-* +build/+ where all the components are built
-  (this includes tools needed to run Buildroot on
-  the host and packages compiled for the target). The +build/+
-  directory contains one subdirectory for each of these components.
+* +build/+ where all the components are built (this includes tools
+  needed by Buildroot on the host and packages compiled for the
+  target). This directory contains one subdirectory for each of these
+  components.
 
 * +staging/+ which contains a hierarchy similar to a root filesystem
-  hierarchy. This directory contains the installation of the
+  hierarchy. This directory contains the headers and libraries of the
   cross-compilation toolchain and all the userspace packages selected
   for the target. However, this directory is 'not' intended to be
   the root filesystem for the target: it contains a lot of development
@@ -109,7 +116,7 @@
 
 These commands, +make menuconfig|nconfig|gconfig|xconfig+ and +make+, are the
 basic ones that allow to easily and quickly generate images fitting
-your needs, with all the supports and applications you enabled.
+your needs, with all the features and applications you enabled.
 
 More details about the "make" command usage are given in
 xref:make-tips[].

[Buildroot] [PATCH 0 of 8 RFCv2 for 2014.08] manual: restructuring and improvements

[Samuel Martin]

Hi Thomas,

On Tue, Aug 12, 2014 at 10:20 PM, Thomas De Schampheleire
<patrickdepinguin@gmail.com> wrote:
> This patch series improves the manual by
> a. reworking the overall structure
> b. improving certain sections wrt clarity and wording
>
> At this point, this is still an RFC as I did not yet go through the entire
> manual. Currently, the overall structure is clear, and the Getting started
> part is finished. During the rest of the month I will cover the User guide
> and Developer guide.

So far, the whole series looks good.

> One of the final patches (not yet included) will reorganize the manual
> source files themselves. Currently, I'm keeping the current names to ease
> reviewing.
>
> It is my goal to make sure this series is in a mergable state before the
> release of 2014.08. If you have any comments or objections against these
> changes, please let me know as soon as possible...
>
> Thanks for your feedback!
>
>

Cheers,

-- 
Samuel

[Buildroot] [PATCH 0 of 8 RFCv2 for 2014.08] manual: restructuring and improvements

[Thomas Petazzoni]

Dear Thomas De Schampheleire,

On Tue, 12 Aug 2014 22:20:05 +0200, Thomas De Schampheleire wrote:

> Thomas De Schampheleire (8)
>   manual: high-level restructuring
>   manual: remove 'Events' section
>   manual/getting started: rename and move 'Getting involved' section
>   manual/getting started: rework 'Community resources' section
>   manual/getting started: rework 'System requirements' section
>   website/download: update daily snapshot section
>   manual/getting started: rework 'Getting Buildroot' section
>   manual/getting started: rework 'Using Buildroot' section

Even though not much review was made on this patch series, I believe
those improvements are generally going in the right direction, and I
know it's painful to rework patch series touching the manual. Also I
believe working on the manual is a really good thing that I'd like to
encourage, so I've applied your patch series as is.

People having comments or additional suggestions are invited to submit
followup patches.

Thanks,

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com