[PATCH] sdk-manual: various cleanups to intro.rst

[PATCH] sdk-manual: various cleanups to intro.rst

[Robert P. J. Day]

Minutiae including grammar fixes, increased brevity and adding a
proper link to another SDK manual section.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
index d966efea7..22af4bec1 100644
--- a/documentation/sdk-manual/intro.rst
+++ b/documentation/sdk-manual/intro.rst
@@ -8,8 +8,8 @@ eSDK Introduction
 =================

 Welcome to the Yocto Project Application Development and the Extensible
-Software Development Kit (eSDK) manual. This manual provides information
-that explains how to use both the Yocto Project extensible and standard
+Software Development Kit (eSDK) manual. This manual
+explains how to use both the Yocto Project extensible and standard
 SDKs to develop applications and images.

 .. note::
@@ -25,12 +25,13 @@ SDKs to develop applications and images.
 All SDKs consist of the following:

 -  *Cross-Development Toolchain*: This toolchain contains a compiler,
-   debugger, and various miscellaneous tools.
+   debugger, and various associated tools.

 -  *Libraries, Headers, and Symbols*: The libraries, headers, and
-   symbols are specific to the image (i.e. they match the image).
+   symbols are specific to the image (i.e. they match the image
+   against which the SDK was built).

--  *Environment Setup Script*: This ``*.sh`` file, once run, sets up the
+-  *Environment Setup Script*: This ``*.sh`` file, once sourced, sets up the
    cross-development environment by defining variables and preparing for
    SDK use.

@@ -48,14 +49,14 @@ time since that path cannot be dynamically altered. This is the reason
 for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext``
 archives.

-Another feature for the SDKs is that only one set of cross-compiler
+Another feature of the SDKs is that only one set of cross-compiler
 toolchain binaries are produced for any given architecture. This feature
 takes advantage of the fact that the target hardware can be passed to
 ``gcc`` as a set of compiler options. Those options are set up by the
 environment script and contained in variables such as
 :term:`CC` and
 :term:`LD`. This reduces the space needed
-for the tools. Understand, however, that every target still needs a
+for the tools. Understand, however, that every target still needs its own
 sysroot because those binaries are target-specific.

 The SDK development environment consists of the following:
@@ -118,8 +119,8 @@ The Cross-Development Toolchain

 The :term:`Cross-Development Toolchain` consists
 of a cross-compiler, cross-linker, and cross-debugger that are used to
-develop user-space applications for targeted hardware. Additionally, for
-an extensible SDK, the toolchain also has built-in ``devtool``
+develop user-space applications for targeted hardwarer; in addition,
+the extensible SDK comes with built-in ``devtool``
 functionality. This toolchain is created by running a SDK installer
 script or through a :term:`Build Directory` that is based on
 your metadata configuration or extension for your targeted device. The
@@ -138,21 +139,19 @@ The QEMU Emulator
 -----------------

 The QEMU emulator allows you to simulate your hardware while running
-your application or image. QEMU is not part of the SDK but is made
-available a number of different ways:
+your application or image. QEMU is not part of the SDK but is
+automatically installed and available if you have done any one of
+the following:

--  If you have cloned the ``poky`` Git repository to create a
-   :term:`Source Directory` and you have
-   sourced the environment setup script, QEMU is installed and
-   automatically available.
+-  cloned the ``poky`` Git repository to create a
+   :term:`Source Directory` and sourced the environment setup script.

--  If you have downloaded a Yocto Project release and unpacked it to
-   create a Source Directory and you have sourced the environment setup
-   script, QEMU is installed and automatically available.
+-  downloaded a Yocto Project release and unpacked it to
+   create a Source Directory and sourced the environment setup
+   script.

--  If you have installed the cross-toolchain tarball and you have
-   sourced the toolchain's setup environment script, QEMU is also
-   installed and automatically available.
+-  installed the cross-toolchain tarball and
+   sourced the toolchain's setup environment script.

 SDK Development Model
 =====================
@@ -202,10 +201,9 @@ You just need to follow these general steps:

    .. note::

-      To use the root filesystem in QEMU, you need to extract it. See
-      the "
-      Extracting the Root Filesystem
-      " section for information on how to extract the root filesystem.
+      To use the root filesystem in QEMU, you need to extract it. See the
+      ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`"
+      section for information on how to do this extraction.

 3. *Develop and Test your Application:* At this point, you have the
    tools to develop your application. If you need to separately install


-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                         http://crashcourse.ca

LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [docs] [PATCH] sdk-manual: various cleanups to intro.rst

[Quentin Schulz]

Hi Robert

On May 1, 2021 6:09:36 PM UTC, "Robert P. J. Day" <rpjday@crashcourse.ca> wrote:
>
>Minutiae including grammar fixes, increased brevity and adding a
>proper link to another SDK manual section.
>
>Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
>---
>
>diff --git a/documentation/sdk-manual/intro.rst b/documentation/sdk-manual/intro.rst
>index d966efea7..22af4bec1 100644
>--- a/documentation/sdk-manual/intro.rst
>+++ b/documentation/sdk-manual/intro.rst
>@@ -8,8 +8,8 @@ eSDK Introduction
> =================
>
> Welcome to the Yocto Project Application Development and the Extensible
>-Software Development Kit (eSDK) manual. This manual provides information
>-that explains how to use both the Yocto Project extensible and standard
>+Software Development Kit (eSDK) manual. This manual
>+explains how to use both the Yocto Project extensible and standard
> SDKs to develop applications and images.
>
> .. note::
>@@ -25,12 +25,13 @@ SDKs to develop applications and images.
> All SDKs consist of the following:
>
> -  *Cross-Development Toolchain*: This toolchain contains a compiler,
>-   debugger, and various miscellaneous tools.
>+   debugger, and various associated tools.
>
> -  *Libraries, Headers, and Symbols*: The libraries, headers, and
>-   symbols are specific to the image (i.e. they match the image).
>+   symbols are specific to the image (i.e. they match the image
>+   against which the SDK was built).
>
>--  *Environment Setup Script*: This ``*.sh`` file, once run, sets up the
>+-  *Environment Setup Script*: This ``*.sh`` file, once sourced, sets up the
>    cross-development environment by defining variables and preparing for
>    SDK use.
>
>@@ -48,14 +49,14 @@ time since that path cannot be dynamically altered. This is the reason
> for a wrapper around the ``populate_sdk`` and ``populate_sdk_ext``
> archives.
>
>-Another feature for the SDKs is that only one set of cross-compiler
>+Another feature of the SDKs is that only one set of cross-compiler
> toolchain binaries are produced for any given architecture. This feature
> takes advantage of the fact that the target hardware can be passed to
> ``gcc`` as a set of compiler options. Those options are set up by the
> environment script and contained in variables such as
> :term:`CC` and
> :term:`LD`. This reduces the space needed
>-for the tools. Understand, however, that every target still needs a
>+for the tools. Understand, however, that every target still needs its own
> sysroot because those binaries are target-specific.
>
> The SDK development environment consists of the following:
>@@ -118,8 +119,8 @@ The Cross-Development Toolchain
>
> The :term:`Cross-Development Toolchain` consists
> of a cross-compiler, cross-linker, and cross-debugger that are used to
>-develop user-space applications for targeted hardware. Additionally, for
>-an extensible SDK, the toolchain also has built-in ``devtool``
>+develop user-space applications for targeted hardwarer; in addition,

Small typo here, should be hardware and not hardwarer I think.

For the rest,
Reviewed-by: Quentin Schulz <foss@0leil.net>

Thanks!
Quentin

>+the extensible SDK comes with built-in ``devtool``
> functionality. This toolchain is created by running a SDK installer
> script or through a :term:`Build Directory` that is based on
> your metadata configuration or extension for your targeted device. The
>@@ -138,21 +139,19 @@ The QEMU Emulator
> -----------------
>
> The QEMU emulator allows you to simulate your hardware while running
>-your application or image. QEMU is not part of the SDK but is made
>-available a number of different ways:
>+your application or image. QEMU is not part of the SDK but is
>+automatically installed and available if you have done any one of
>+the following:
>
>--  If you have cloned the ``poky`` Git repository to create a
>-   :term:`Source Directory` and you have
>-   sourced the environment setup script, QEMU is installed and
>-   automatically available.
>+-  cloned the ``poky`` Git repository to create a
>+   :term:`Source Directory` and sourced the environment setup script.
>
>--  If you have downloaded a Yocto Project release and unpacked it to
>-   create a Source Directory and you have sourced the environment setup
>-   script, QEMU is installed and automatically available.
>+-  downloaded a Yocto Project release and unpacked it to
>+   create a Source Directory and sourced the environment setup
>+   script.
>
>--  If you have installed the cross-toolchain tarball and you have
>-   sourced the toolchain's setup environment script, QEMU is also
>-   installed and automatically available.
>+-  installed the cross-toolchain tarball and
>+   sourced the toolchain's setup environment script.
>
> SDK Development Model
> =====================
>@@ -202,10 +201,9 @@ You just need to follow these general steps:
>
>    .. note::
>
>-      To use the root filesystem in QEMU, you need to extract it. See
>-      the "
>-      Extracting the Root Filesystem
>-      " section for information on how to extract the root filesystem.
>+      To use the root filesystem in QEMU, you need to extract it. See the
>+      ":ref:`sdk-manual/appendix-obtain:extracting the root filesystem`"
>+      section for information on how to do this extraction.
>
> 3. *Develop and Test your Application:* At this point, you have the
>    tools to develop your application. If you need to separately install
>
>
>-- 
>
>========================================================================
>Robert P. J. Day                                 Ottawa, Ontario, CANADA
>                         http://crashcourse.ca
>
>LinkedIn:                               http://ca.linkedin.com/in/rpjday
>========================================================================

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

Re: [docs] [PATCH] sdk-manual: various cleanups to intro.rst

[Michael Opdenacker]

Hi Robert,

Thanks for these improvements!

On 5/1/21 9:11 PM, Quentin Schulz wrote:
>
>> Welcome to the Yocto Project Application Development and the Extensible
>> -Software Development Kit (eSDK) manual. This manual provides information
>> -that explains how to use both the Yocto Project extensible and standard
>> +Software Development Kit (eSDK) manual. This manual
>> +explains how to use both the Yocto Project extensible and standard
>> SDKs to develop applications and images.


Actually, I caught multiple ones like this while reading the manuals
(still ongoing work). I'll submit more such improvements. Sometimes the
style is too verbose indeed.

>> The :term:`Cross-Development Toolchain` consists
>> of a cross-compiler, cross-linker, and cross-debugger that are used to
>> -develop user-space applications for targeted hardware. Additionally, for
>> -an extensible SDK, the toolchain also has built-in ``devtool``
>> +develop user-space applications for targeted hardwarer; in addition,
> Small typo here, should be hardware and not hardwarer I think.

I've fixed it and merged your patch into "master-next", with my
"Reviewed-by" note too.

Thanks to you both Robert and Quentin,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] sdk-manual: various cleanups to intro.rst

[Robert P. J. Day]

On Mon, 3 May 2021, Michael Opdenacker wrote:

> Hi Robert,
>
> Thanks for these improvements!
>
> On 5/1/21 9:11 PM, Quentin Schulz wrote:
> >
> >> Welcome to the Yocto Project Application Development and the Extensible
> >> -Software Development Kit (eSDK) manual. This manual provides information
> >> -that explains how to use both the Yocto Project extensible and standard
> >> +Software Development Kit (eSDK) manual. This manual
> >> +explains how to use both the Yocto Project extensible and standard
> >> SDKs to develop applications and images.
>
> Actually, I caught multiple ones like this while reading the manuals
> (still ongoing work). I'll submit more such improvements. Sometimes
> the style is too verbose indeed.

  i've noticed the prevalence of unnecessary prose in lots of places.
example:

  "To frobnicate the fubar, run the following command:"

when it should say simply:

  "To frobnicate the fubar, run:"

and so on.

  i can't remember who said it, but some literary giant once said
something like, "half my time is spent writing, the other half
throwing away what shouldn't be there."

rday

Re: [docs] [PATCH] sdk-manual: various cleanups to intro.rst

[Michael Opdenacker]

Hi Robert,

On 5/3/21 4:30 PM, Robert P. J. Day wrote:
>
>   i've noticed the prevalence of unnecessary prose in lots of places.
> example:
>
>   "To frobnicate the fubar, run the following command:"
>
> when it should say simply:
>
>   "To frobnicate the fubar, run:"
>
> and so on.

Definitely agree. Indeed, there are many instances of "the following"
worth inspecting.

I've also found unnecessary instances of "exists", such as:

"support also exists for systemd"

while I would just say:

"systemd is also supported"

And this was a simple case!

>
>   i can't remember who said it, but some literary giant once said
> something like, "half my time is spent writing, the other half
> throwing away what shouldn't be there."


I cannot find the original quote, but yes, it makes sense. I'll probably
get a new pass on my copy of the "Elements of Style" book :)

Cheers,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] sdk-manual: various cleanups to intro.rst

[Robert P. J. Day]

On Mon, 3 May 2021, Michael Opdenacker wrote:

> I cannot find the original quote, but yes, it makes sense. I'll
> probably get a new pass on my copy of the "Elements of Style" book
> :)

  barf. instead, get a copy of:

https://www.goodreads.com/book/show/16887.How_to_Write

rday

Re: [docs] [PATCH] sdk-manual: various cleanups to intro.rst

[Robert P. J. Day]

  for sheer, unadulterated savagery in shredding someone's literary
talent, i give you mark twain eviscerating american author james
fenimore cooper:

https://twain.lib.virginia.edu/projects/rissetto/offense.html

rday