manual: use one-line titles instead of two-line titles (trivial)

Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).

The two-line title underlines are:
Level 0 (top level):     ======================
Level 1:                 ----------------------
Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level):  ++++++++++++++++++++++

and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==

=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====

The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:

- asciidoc also uses some of the underline symbols for other purposes (like
  preformatted code, example blocks, ...), which makes it difficult to do
  mass replacements, such as a planned follow-up patch that needs to move
  all sections one level down.

- it is difficult to remember which level a given underline symbol (=-~^+)
  corresponds to, while counting = signs is easy.

This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.

----------------------------------------------------------------------------
#!/usr/bin/env python

import sys
import mmap
import re

for input in sys.argv[1:]:

    f = open(input, 'r+')
    f.flush()
    s = mmap.mmap(f.fileno(), 0)

    # Level 0 (top level):     ======================   =
    # Level 1:                 ----------------------   ==
    # Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~   ===
    # Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^   ====
    # Level 4 (bottom level):  ++++++++++++++++++++++   =====

    def replace_title(s, symbol, replacement):
        pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
        return pattern.sub(r'%s \1' % replacement, s)

    new = s
    new = replace_title(new, '=', '=')
    new = replace_title(new, '+', '=====')
    new = replace_title(new, '^', '====')
    new = replace_title(new, '~', '===')
    #new = replace_title(new, '-', '==')

    s.seek(0)
    s.write(new)
    s.resize(s.tell())
    s.close()
    f.close()

----------------------------------------------------------------------------

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

1 files changed, 8 insertions, 16 deletions

diff --git a/docs/manual/patch-policy.txt b/docs/manual/patch-policy.txt
index c67d684fb2..cb39821492 100644
--- a/docs/manual/patch-policy.txt
+++ b/docs/manual/patch-policy.txt
@@ -3,8 +3,7 @@
 
 [[patch-policy]]
 
-Patching a package
-------------------
+== Patching a package
 
 While integrating a new package or updating an existing one, it may be
 necessary to patch the source of the software to get it cross-built within
@@ -15,11 +14,9 @@ the builds. It supports three ways of applying patch sets: downloaded patches,
 patches supplied within buildroot and patches located in a user-defined
 global patch directory.
 
-Providing patches
-~~~~~~~~~~~~~~~~~
+=== Providing patches
 
-Downloaded
-^^^^^^^^^^
+==== Downloaded
 
 If it is necessary to apply a patch that is available for download, then add it
 to the +<packagename>_PATCH+ variable. It is downloaded from the same site
@@ -28,8 +25,7 @@ patch series.
 
 This method is typically used for packages from Debian.
 
-Within Buildroot
-^^^^^^^^^^^^^^^^
+==== Within Buildroot
 
 Most patches are provided within Buildroot, in the package
 directory; these typically aim to fix cross-compilation, libc support,
@@ -46,8 +42,7 @@ application order.
 reference in their filename.
 - The field +<number>+ in the patch file name refers to the 'apply order'.
 
-Global patch directory
-^^^^^^^^^^^^^^^^^^^^^^
+==== Global patch directory
 
 The +BR2_GLOBAL_PATCH_DIR+ configuration file option can be
 used to specify a space separated list of one or more directories
@@ -55,8 +50,7 @@ containing global package patches. See xref:packages-custom[] for
 details.
 
 [[patch-apply-order]]
-How patches are applied
-~~~~~~~~~~~~~~~~~~~~~~~
+=== How patches are applied
 
 . Run the +<packagename>_PRE_PATCH_HOOKS+ commands if defined;
 
@@ -87,8 +81,7 @@ How patches are applied
 
 If something goes wrong in the steps _3_ or _4_, then the build fails.
 
-Format and licensing of the package patches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Format and licensing of the package patches
 
 Patches are released under the same license as the software that is
 modified.
@@ -130,8 +123,7 @@ AC_PROG_MAKE_SET
 +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
 ---------------
 
-Integrating patches found on the Web
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Integrating patches found on the Web
 
 When integrating a patch of which you are not the author, you have to
 add a few things in the header of the patch itself.