2012-11-11 04:14:42 +01:00
|
|
|
// -*- mode:doc; -*-
|
2013-02-13 13:59:02 +01:00
|
|
|
// vim: set syntax=asciidoc:
|
2012-11-11 04:14:42 +01:00
|
|
|
|
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>
2014-05-02 07:47:30 +02:00
|
|
|
= The Buildroot user manual
|
2011-10-10 10:46:39 +02:00
|
|
|
:toc:
|
|
|
|
|
|
2014-05-28 19:29:51 +02:00
|
|
|
Buildroot {sys:echo $\{BR2_VERSION%%-git*\}} manual generated on {localdate}
|
|
|
|
|
{localtime} from git revision {sys:git rev-parse --short HEAD}
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2014-05-28 19:29:51 +02:00
|
|
|
The Buildroot manual is written by the Buildroot developers.
|
|
|
|
|
It is licensed under the GNU General Public License, version 2. Refer to the
|
docs/manual: always point to the correct license file
The manual is GPL-2, and points to the COPYING file in the repository.
When we do a rendering of the manual for a specific version, that URL
is currently always poitning to the latest version of the COPYING file.
If we ever have to change the content of that file (e.g. to add a new
exception, more clarifications, a license change, or whatever), then
an old manual would point to that newer version, which would then be
incorrect.
Include the sha1 of the commit in the URL, so that the manual always
point to the tree at the time the manual was rendered, not the time
it is consulted. Contrary to the informative text above, use the full
sha1, not the shortened one.
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Cc: Thomas De Schampheleire <patrickdepinguin@gmail.com>
Cc: Luca Ceresoli <luca@lucaceresoli.net>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2018-06-02 10:01:01 +02:00
|
|
|
http://git.buildroot.org/buildroot/tree/COPYING?id={sys:git rev-parse HEAD}[COPYING]
|
|
|
|
|
file in the Buildroot sources for the full text of this license.
|
2014-05-27 21:34:13 +02:00
|
|
|
|
2019-01-06 21:30:34 +01:00
|
|
|
Copyright (C) 2004-2019 The Buildroot developers
|
2013-03-25 14:28:04 +01:00
|
|
|
|
2011-10-10 10:46:39 +02:00
|
|
|
image::logo.png[]
|
|
|
|
|
|
manual: high-level restructuring
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>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
2014-08-12 22:20:06 +02:00
|
|
|
= Getting started
|
2011-10-10 10:46:39 +02:00
|
|
|
|
|
|
|
|
include::introduction.txt[]
|
|
|
|
|
|
2014-08-20 21:39:53 +02:00
|
|
|
include::prerequisite.txt[]
|
|
|
|
|
|
|
|
|
|
include::getting.txt[]
|
|
|
|
|
|
2014-08-20 21:39:54 +02:00
|
|
|
include::quickstart.txt[]
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2014-08-20 21:39:54 +02:00
|
|
|
include::resources.txt[]
|
2014-08-12 22:20:08 +02:00
|
|
|
|
manual: high-level restructuring
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>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
2014-08-12 22:20:06 +02:00
|
|
|
= User guide
|
|
|
|
|
|
2014-08-20 21:39:53 +02:00
|
|
|
include::configure.txt[]
|
|
|
|
|
|
|
|
|
|
include::configure-other-components.txt[]
|
|
|
|
|
|
|
|
|
|
include::common-usage.txt[]
|
|
|
|
|
|
|
|
|
|
include::customize.txt[]
|
2011-10-10 10:46:39 +02:00
|
|
|
|
2012-11-11 04:14:50 +01:00
|
|
|
include::faq-troubleshooting.txt[]
|
|
|
|
|
|
2013-10-06 19:49:07 +02:00
|
|
|
include::known-issues.txt[]
|
|
|
|
|
|
2012-11-11 04:14:58 +01:00
|
|
|
include::legal-notice.txt[]
|
|
|
|
|
|
2012-11-11 04:15:01 +01:00
|
|
|
include::beyond-buildroot.txt[]
|
|
|
|
|
|
manual: high-level restructuring
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>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
2014-08-12 22:20:06 +02:00
|
|
|
= Developer guide
|
|
|
|
|
|
2014-08-19 21:41:47 +02:00
|
|
|
include::how-buildroot-works.txt[]
|
|
|
|
|
|
2014-08-20 21:39:53 +02:00
|
|
|
include::writing-rules.txt[]
|
|
|
|
|
|
2014-09-18 21:39:24 +02:00
|
|
|
include::adding-board-support.txt[]
|
|
|
|
|
|
2014-08-20 21:39:53 +02:00
|
|
|
include::adding-packages.txt[]
|
|
|
|
|
|
|
|
|
|
include::patch-policy.txt[]
|
|
|
|
|
|
|
|
|
|
include::download-infra.txt[]
|
|
|
|
|
|
|
|
|
|
include::debugging-buildroot.txt[]
|
manual: high-level restructuring
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>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
2014-08-12 22:20:06 +02:00
|
|
|
|
2012-11-11 04:14:53 +01:00
|
|
|
include::contribute.txt[]
|
|
|
|
|
|
2016-09-12 22:54:55 +02:00
|
|
|
include::developers.txt[]
|
|
|
|
|
|
manual: high-level restructuring
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>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
2014-08-12 22:20:06 +02:00
|
|
|
= Appendix
|
|
|
|
|
|
2012-02-18 00:30:58 +01:00
|
|
|
include::appendix.txt[]
|
