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, 7 insertions, 14 deletions

diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt
index c9d5eb967b..3d5842d333 100644
--- a/docs/manual/common-usage.txt
+++ b/docs/manual/common-usage.txt
@@ -1,13 +1,11 @@
 // -*- mode:doc; -*-
 // vim: set syntax=asciidoc:
 
-Daily use
----------
+== Daily use
 
 include::rebuilding-packages.txt[]
 
-Offline builds
-~~~~~~~~~~~~~~
+=== Offline builds
 
 If you intend to do an offline build and just want to download
 all sources that you previously selected in the configurator
@@ -20,8 +18,7 @@ all sources that you previously selected in the configurator
 You can now disconnect or copy the content of your +dl+
 directory to the build-host.
 
-Building out-of-tree
-~~~~~~~~~~~~~~~~~~~~
+=== Building out-of-tree
 
 As default, everything built by Buildroot is stored in the directory
 +output+ in the Buildroot tree.
@@ -63,8 +60,7 @@ and +-C <...>+, simply run (in the output directory):
 
 [[env-vars]]
 
-Environment variables
-~~~~~~~~~~~~~~~~~~~~~
+=== Environment variables
 
 Buildroot also honors some environment variables, when they are passed
 to +make+ or set in the environment:
@@ -113,8 +109,7 @@ or +g+++ for building helper-binaries on your host, then do
  $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD
 --------------------
 
-Dealing efficiently with filesystem images
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Dealing efficiently with filesystem images
 
 Filesystem images can get pretty big, depending on the filesystem you choose,
 the number of packages, whether you provisioned free space... Yet, some
@@ -152,8 +147,7 @@ your filesystem, those parts may not be all-zeroes when read back). You
 should only use sparse files when handling files on the build machine, not
 when transferring them to an actual device that will be used on the target.
 
-Graphing the dependencies between packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Graphing the dependencies between packages
 
 [[graph-depends]]
 
@@ -204,8 +198,7 @@ supported.
 BR2_GRAPH_OUT=svg make graph-depends
 --------------------------------
 
-Graphing the build duration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Graphing the build duration
 
 [[graph-duration]]