[Buildroot] [PATCH 6/9] manual: introduction.txt: enhance Buildroot presentation

[Thomas De Schampheleire]

Hi Samuel,

On Sat, Oct 5, 2013 at 9:49 PM, Samuel Martin <s.martin49 at gmail.com> wrote:
> * add a "What is Buildroot and what it is not" section
> * add a "Buildroot's principles" section
>
> Signed-off-by: Samuel Martin <s.martin49 at gmail.com>
> ---
>  docs/manual/introduction.txt | 40 ++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
>
> diff --git a/docs/manual/introduction.txt b/docs/manual/introduction.txt
> index c014565..0838c48 100644
> --- a/docs/manual/introduction.txt
> +++ b/docs/manual/introduction.txt
> @@ -25,3 +25,43 @@ comes with default configurations for several boards available
>  off-the-shelf. Besides this, a number of third-party projects are based on,
>  or develop their BSP footnote:[BSP: Board Support Package] or
>  SDK footnote:[SDK: Software Development Kit] on top of Buildroot.
> +
> +What is Buildroot and what it is not
> +------------------------------------

I think it should be ".. and what is it not" to match the first part
of the sentence.
An alternative would be "What Buildroot is and what it is not" but I
prefer the first one.

> +
> +Buildroot is:
> +
> +* a community-driven project
> +* a tool uses in the industry

used

> +* Buildroot targets embedded, rather small, often headless, devices

This does not match the list header:
Buildroot is Buildroot targets embedded, ...


But I'm not sure this part is very useful: 'buildroot is a tool used
in the industry', but a drilling machine is also a tool used in the
industry.

Moreover, there already is an explanation of what buildroot is in the
'about buildroot' section earlier in this file. The interesting part
is mainly what it is _not_.

> +
> +
> +Buildroot is *not*:
> +
> +* a _classic Linux-based distribution_, this means:
> +
> +** Buildroot root-filesystems are not managed by any package manager,

Is this technically the right way to put it?
What about:
Buildroot does not use any package manager to populate the root filesystem,

> +   this means there is no way to update only one package of a root-filesystem
> +   built by Buildroot without regenerating the whole root-filesystem;
> +** Buildroot does not keep track of each package's content;
> +** Buildroot does not provide as many packages as others distributions do;
> +   so, some packages may be not available yet because the community does not

may not be available

> +   need them or think they are not suitable for embedded targets.

(the community) thinks

> +
> +* Root filesystem generated by Buildroot are not intend to be used for

filesystems
intended

and you are currently mixing the spelling 'root-filesystem' and 'root
filesystem'. My personal preference is 'root filesystem' or if written
in short 'rootfs'.

> +  native development; so they do not contain any development file (no header,
> +  no static library, no native compiler for the target), nor documentation.

I would put this in plural:
... any development files (no headers, no static libraries, no native
compiler for the target), ...

> +
> +Buildroot's principles
> +----------------------
> +
> +* Easy to use
> +* Quick build

This could be 'Fast to build' to match the first and fourth item's composition.

> +* Small footprint of the generated images footnote:[the smallness of the
> +image footprint mostly depends on the target device and its application(s)]
> +* Easy to hack
> +* Being generic, but allowing customization:
> +
> +** Provide support for SoC, rather than board specific configuration (though
> +Buildroot comes with a set of default configurations for a bunch of boards);
> +** Provide default configuration that can be easily overriden.
> --


Best regards,
Thomas