* [PATCH 0/1] YP overview manual: style improvements
@ 2021-03-30 15:19 Michael Opdenacker
2021-03-30 15:19 ` [PATCH 1/1] " Michael Opdenacker
0 siblings, 1 reply; 9+ messages in thread
From: Michael Opdenacker @ 2021-03-30 15:19 UTC (permalink / raw)
To: docs
I'm starting to read the YP manuals to better understand the
project and its resources.
This is also an opportunity to propose style updates, and
sometimes a more correct way of explaining some concepts.
Here are my first proposed improvements, this time
on the first part of the YP Overview Manual.
Note that this document was reviewed on an e-book reader
through Sphinx' "epub" export ("make epub"). Don't hesitate
to try this too, the output is pretty good, except for the graphics
that would need upscaling (at least in my case), but this
is another topic.
Thanks in advance for your reviews!
Michael.
^ permalink raw reply [flat|nested] 9+ messages in thread* [PATCH 1/1] YP overview manual: style improvements 2021-03-30 15:19 [PATCH 0/1] YP overview manual: style improvements Michael Opdenacker @ 2021-03-30 15:19 ` Michael Opdenacker 2021-03-30 19:50 ` [docs] " Khem Raj 0 siblings, 1 reply; 9+ messages in thread From: Michael Opdenacker @ 2021-03-30 15:19 UTC (permalink / raw) To: docs; +Cc: Michael Opdenacker - A few style improvements - Fix a few typos - Fix one of these typos happening in ref-manual/migration-2.1.rst too Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> --- documentation/overview-manual/yp-intro.rst | 54 +++++++++++----------- documentation/ref-manual/migration-2.1.rst | 2 +- 2 files changed, 29 insertions(+), 27 deletions(-) diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst index 176e5b24c..b146db5e4 100644 --- a/documentation/overview-manual/yp-intro.rst +++ b/documentation/overview-manual/yp-intro.rst @@ -41,9 +41,9 @@ Features The following list describes features and advantages of the Yocto Project: -- *Widely Adopted Across the Industry:* Semiconductor, operating - system, software, and service vendors exist whose products and - services adopt and support the Yocto Project. For a look at the Yocto +- *Widely Adopted Across the Industry:* Many semiconductor, operating + system, software, and service vendors adopt and support the Yocto + Project in their products and services. For a look at the Yocto Project community and the companies involved with the Yocto Project, see the "COMMUNITY" and "ECOSYSTEM" tabs on the :yocto_home:`Yocto Project <>` home page. @@ -53,8 +53,8 @@ Project: create and supply BSPs that support their hardware. If you have custom silicon, you can create a BSP that supports that architecture. - Aside from lots of architecture support, the Yocto Project fully - supports a wide range of device emulation through the Quick EMUlator + Aside from broad architecture support, the Yocto Project fully + supports a wide range of devices emulated by the Quick EMUlator (QEMU). - *Images and Code Transfer Easily:* Yocto Project output can easily @@ -78,10 +78,10 @@ Project: you need for embedded devices. You only add the feature support or packages that you absolutely need for the device. For devices that have display hardware, you can use available system components such - as X11, GTK+, Qt, Clutter, and SDL (among others) to create a rich - user experience. For devices that do not have a display or where you - want to use alternative UI frameworks, you can choose to not install - these components. + as X11, Wayland, GTK+, Qt, Clutter, and SDL (among others) to create + a rich user experience. For devices that do not have a display or + where you want to use alternative UI frameworks, you can choose to + not build these components. - *Comprehensive Toolchain Capabilities:* Toolchains for supported architectures satisfy most use cases. However, if your hardware @@ -431,11 +431,14 @@ activities using the Yocto Project: During a build, it can be necessary to perform operations that require system administrator privileges. For example, file ownership - or permissions might need definition. Pseudo is a tool that you can - either use directly or through the environment variable + or permissions might need to be defined. Pseudo is a tool that you + can either use directly or through the environment variable ``LD_PRELOAD``. Either method allows these operations to succeed as if system administrator privileges exist even when they do not. + Thanks to Pseudo, the Yocto Project never needs root privileges to + build images for your target system. + You can read more about Pseudo in the "`Fakeroot and Pseudo <#fakeroot-and-pseudo>`__" section. @@ -574,11 +577,11 @@ Development Methods The Yocto Project development environment usually involves a :term:`Build Host` and target hardware. You use the Build Host to build images and develop -applications, while you use the target hardware to test deployed +applications, while you use the target hardware to execute deployed software. This section provides an introduction to the choices or development -methods you have when setting up your Build Host. Depending on the your +methods you have when setting up your Build Host. Depending on your particular workflow preference and the type of operating system your Build Host runs, several choices exist that allow you to use the Yocto Project. @@ -593,7 +596,7 @@ Project. system running Linux as its native operating system allows you to develop software by directly using the :term:`BitBake` tool. You can - accomplish all aspects of development from a familiar shell of a + accomplish all aspects of development from a regular shell in a supported Linux distribution. For information on how to set up a Build Host on a system running @@ -622,7 +625,7 @@ Project. section in the Yocto Project Development Tasks Manual. - *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem - For Linux v2 to set up a build host using Windows 10. + For Linux v2 to set up a Build Host using Windows 10. .. note:: @@ -631,8 +634,7 @@ Project. still decide to use WSL please upgrade to WSLv2. The Windows Subsystem For Linux allows Windows 10 to run a real Linux - kernel inside of a lightweight utility virtual machine (VM) using - virtualization technology. + kernel inside of a lightweight virtual machine (VM). For information on how to set up a Build Host with WSLv2, see the ":ref:`dev-manual/start:setting up to use windows subsystem for linux (wslv2)`" @@ -641,10 +643,9 @@ Project. - *Toaster:* Regardless of what your Build Host is running, you can use Toaster to develop software using the Yocto Project. Toaster is a web interface to the Yocto Project's :term:`OpenEmbedded Build System`. - The interface - enables you to configure and run your builds. Information about - builds is collected and stored in a database. You can use Toaster to - configure and start builds on multiple remote build servers. + The interface allows you to configure and run your builds. Information + about builds is collected and stored in a database. You can use Toaster + to configure and start builds on multiple remote build servers. For information about and how to use Toaster, see the :doc:`/toaster-manual/index`. @@ -816,9 +817,9 @@ helpful for getting started: isolate information used when building for multiple architectures. Layers are hierarchical in their ability to override previous specifications. You can include any number of available layers from - the Yocto Project and customize the build by adding your layers after - them. You can search the Layer Index for layers used within Yocto - Project. + the Yocto Project and customize the build by adding your own layers + after them. You can search the Layer Index for layers used within + Yocto Project. For more detailed information on layers, see the ":ref:`dev-manual/common-tasks:understanding and creating layers`" @@ -851,7 +852,7 @@ helpful for getting started: BitBake is similar to the ``make`` tool. During a build process, the build system tracks dependencies and - performs a native or cross-compilation of the package. As a first + performs a native or cross-compilation of each package. As a first step in a cross-build setup, the framework attempts to create a cross-compiler toolchain (i.e. Extensible SDK) suited for the target platform. @@ -878,7 +879,8 @@ helpful for getting started: subtle meanings. For example, the packages referred to in the ":ref:`ref-manual/system-requirements:required packages for the build host`" section in the Yocto Project Reference Manual are compiled binaries - that, when installed, add functionality to your Linux distribution. + that, when installed, add functionality to your host Linux + distribution. Another point worth noting is that historically within the Yocto Project, recipes were referred to as packages - thus, the existence diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst index 861d04861..4a5acc45c 100644 --- a/documentation/ref-manual/migration-2.1.rst +++ b/documentation/ref-manual/migration-2.1.rst @@ -134,7 +134,7 @@ or that mention ``do_rootfs``, you might need to update those changes. In particular, if you had added any tasks after ``do_rootfs``, you should make edits so that those tasks are after the :ref:`ref-tasks-image-complete` task rather than -after ``do_rootfs`` so that the your added tasks run at the correct +after ``do_rootfs`` so that your added tasks run at the correct time. A minor part of this restructuring is that the post-processing -- 2.25.1 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [docs] [PATCH 1/1] YP overview manual: style improvements 2021-03-30 15:19 ` [PATCH 1/1] " Michael Opdenacker @ 2021-03-30 19:50 ` Khem Raj 2021-03-31 9:14 ` Michael Opdenacker 0 siblings, 1 reply; 9+ messages in thread From: Khem Raj @ 2021-03-30 19:50 UTC (permalink / raw) To: Michael Opdenacker, docs On 3/30/21 8:19 AM, Michael Opdenacker wrote: > - A few style improvements > - Fix a few typos > - Fix one of these typos happening in ref-manual/migration-2.1.rst > too > thanks, this looks great, I was curious if the formatting piece will be automatic for display, right ? or do we need some work in that direction too. > Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> > --- > documentation/overview-manual/yp-intro.rst | 54 +++++++++++----------- > documentation/ref-manual/migration-2.1.rst | 2 +- > 2 files changed, 29 insertions(+), 27 deletions(-) > > diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst > index 176e5b24c..b146db5e4 100644 > --- a/documentation/overview-manual/yp-intro.rst > +++ b/documentation/overview-manual/yp-intro.rst > @@ -41,9 +41,9 @@ Features > The following list describes features and advantages of the Yocto > Project: > > -- *Widely Adopted Across the Industry:* Semiconductor, operating > - system, software, and service vendors exist whose products and > - services adopt and support the Yocto Project. For a look at the Yocto > +- *Widely Adopted Across the Industry:* Many semiconductor, operating > + system, software, and service vendors adopt and support the Yocto > + Project in their products and services. For a look at the Yocto > Project community and the companies involved with the Yocto Project, > see the "COMMUNITY" and "ECOSYSTEM" tabs on the > :yocto_home:`Yocto Project <>` home page. > @@ -53,8 +53,8 @@ Project: > create and supply BSPs that support their hardware. If you have > custom silicon, you can create a BSP that supports that architecture. > > - Aside from lots of architecture support, the Yocto Project fully > - supports a wide range of device emulation through the Quick EMUlator > + Aside from broad architecture support, the Yocto Project fully > + supports a wide range of devices emulated by the Quick EMUlator > (QEMU). > > - *Images and Code Transfer Easily:* Yocto Project output can easily > @@ -78,10 +78,10 @@ Project: > you need for embedded devices. You only add the feature support or > packages that you absolutely need for the device. For devices that > have display hardware, you can use available system components such > - as X11, GTK+, Qt, Clutter, and SDL (among others) to create a rich > - user experience. For devices that do not have a display or where you > - want to use alternative UI frameworks, you can choose to not install > - these components. > + as X11, Wayland, GTK+, Qt, Clutter, and SDL (among others) to create > + a rich user experience. For devices that do not have a display or > + where you want to use alternative UI frameworks, you can choose to > + not build these components. > > - *Comprehensive Toolchain Capabilities:* Toolchains for supported > architectures satisfy most use cases. However, if your hardware > @@ -431,11 +431,14 @@ activities using the Yocto Project: > > During a build, it can be necessary to perform operations that > require system administrator privileges. For example, file ownership > - or permissions might need definition. Pseudo is a tool that you can > - either use directly or through the environment variable > + or permissions might need to be defined. Pseudo is a tool that you > + can either use directly or through the environment variable > ``LD_PRELOAD``. Either method allows these operations to succeed as > if system administrator privileges exist even when they do not. > > + Thanks to Pseudo, the Yocto Project never needs root privileges to > + build images for your target system. > + > You can read more about Pseudo in the "`Fakeroot and > Pseudo <#fakeroot-and-pseudo>`__" section. > > @@ -574,11 +577,11 @@ Development Methods > The Yocto Project development environment usually involves a > :term:`Build Host` and target > hardware. You use the Build Host to build images and develop > -applications, while you use the target hardware to test deployed > +applications, while you use the target hardware to execute deployed > software. > > This section provides an introduction to the choices or development > -methods you have when setting up your Build Host. Depending on the your > +methods you have when setting up your Build Host. Depending on your > particular workflow preference and the type of operating system your > Build Host runs, several choices exist that allow you to use the Yocto > Project. > @@ -593,7 +596,7 @@ Project. > system running Linux as its native operating system allows you to > develop software by directly using the > :term:`BitBake` tool. You can > - accomplish all aspects of development from a familiar shell of a > + accomplish all aspects of development from a regular shell in a > supported Linux distribution. > > For information on how to set up a Build Host on a system running > @@ -622,7 +625,7 @@ Project. > section in the Yocto Project Development Tasks Manual. > > - *Windows Subsystem For Linux (WSLv2):* You may use Windows Subsystem > - For Linux v2 to set up a build host using Windows 10. > + For Linux v2 to set up a Build Host using Windows 10. > > .. note:: > > @@ -631,8 +634,7 @@ Project. > still decide to use WSL please upgrade to WSLv2. > > The Windows Subsystem For Linux allows Windows 10 to run a real Linux > - kernel inside of a lightweight utility virtual machine (VM) using > - virtualization technology. > + kernel inside of a lightweight virtual machine (VM). > > For information on how to set up a Build Host with WSLv2, see the > ":ref:`dev-manual/start:setting up to use windows subsystem for linux (wslv2)`" > @@ -641,10 +643,9 @@ Project. > - *Toaster:* Regardless of what your Build Host is running, you can use > Toaster to develop software using the Yocto Project. Toaster is a web > interface to the Yocto Project's :term:`OpenEmbedded Build System`. > - The interface > - enables you to configure and run your builds. Information about > - builds is collected and stored in a database. You can use Toaster to > - configure and start builds on multiple remote build servers. > + The interface allows you to configure and run your builds. Information > + about builds is collected and stored in a database. You can use Toaster > + to configure and start builds on multiple remote build servers. > > For information about and how to use Toaster, see the > :doc:`/toaster-manual/index`. > @@ -816,9 +817,9 @@ helpful for getting started: > isolate information used when building for multiple architectures. > Layers are hierarchical in their ability to override previous > specifications. You can include any number of available layers from > - the Yocto Project and customize the build by adding your layers after > - them. You can search the Layer Index for layers used within Yocto > - Project. > + the Yocto Project and customize the build by adding your own layers > + after them. You can search the Layer Index for layers used within > + Yocto Project. > > For more detailed information on layers, see the > ":ref:`dev-manual/common-tasks:understanding and creating layers`" > @@ -851,7 +852,7 @@ helpful for getting started: > BitBake is similar to the ``make`` tool. > > During a build process, the build system tracks dependencies and > - performs a native or cross-compilation of the package. As a first > + performs a native or cross-compilation of each package. As a first > step in a cross-build setup, the framework attempts to create a > cross-compiler toolchain (i.e. Extensible SDK) suited for the target > platform. > @@ -878,7 +879,8 @@ helpful for getting started: > subtle meanings. For example, the packages referred to in the > ":ref:`ref-manual/system-requirements:required packages for the build host`" > section in the Yocto Project Reference Manual are compiled binaries > - that, when installed, add functionality to your Linux distribution. > + that, when installed, add functionality to your host Linux > + distribution. > > Another point worth noting is that historically within the Yocto > Project, recipes were referred to as packages - thus, the existence > diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst > index 861d04861..4a5acc45c 100644 > --- a/documentation/ref-manual/migration-2.1.rst > +++ b/documentation/ref-manual/migration-2.1.rst > @@ -134,7 +134,7 @@ or that mention ``do_rootfs``, you might need to update those changes. > In particular, if you had added any tasks after ``do_rootfs``, you > should make edits so that those tasks are after the > :ref:`ref-tasks-image-complete` task rather than > -after ``do_rootfs`` so that the your added tasks run at the correct > +after ``do_rootfs`` so that your added tasks run at the correct > time. > > A minor part of this restructuring is that the post-processing > > > > > ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [docs] [PATCH 1/1] YP overview manual: style improvements 2021-03-30 19:50 ` [docs] " Khem Raj @ 2021-03-31 9:14 ` Michael Opdenacker 2021-03-31 15:39 ` Khem Raj 0 siblings, 1 reply; 9+ messages in thread From: Michael Opdenacker @ 2021-03-31 9:14 UTC (permalink / raw) To: Khem Raj, docs Hi Khem, Thanks for your review! On 3/30/21 9:50 PM, Khem Raj wrote: > > > On 3/30/21 8:19 AM, Michael Opdenacker wrote: >> - A few style improvements >> - Fix a few typos >> - Fix one of these typos happening in ref-manual/migration-2.1.rst >> too >> > > thanks, this looks great, I was curious if the formatting piece will > be automatic for display, right ? or do we need some work in that > direction too. Oops, I must confess I'm not sure I understand what you mean here. Could you elaborate? Cheers, Michael. -- Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [docs] [PATCH 1/1] YP overview manual: style improvements 2021-03-31 9:14 ` Michael Opdenacker @ 2021-03-31 15:39 ` Khem Raj 2021-04-02 12:47 ` Michael Opdenacker [not found] ` <16720B54D46DA7C3.28438@lists.yoctoproject.org> 0 siblings, 2 replies; 9+ messages in thread From: Khem Raj @ 2021-03-31 15:39 UTC (permalink / raw) To: Michael Opdenacker; +Cc: docs On Wed, Mar 31, 2021 at 2:14 AM Michael Opdenacker <michael.opdenacker@bootlin.com> wrote: > > Hi Khem, > > Thanks for your review! > > On 3/30/21 9:50 PM, Khem Raj wrote: > > > > > > On 3/30/21 8:19 AM, Michael Opdenacker wrote: > >> - A few style improvements > >> - Fix a few typos > >> - Fix one of these typos happening in ref-manual/migration-2.1.rst > >> too > >> > > > > thanks, this looks great, I was curious if the formatting piece will > > be automatic for display, right ? or do we need some work in that > > direction too. > > > Oops, I must confess I'm not sure I understand what you mean here. Could > you elaborate? > the left and right margins, how do they look on epub readers for this document was what I was wondering. > Cheers, > > Michael. > > -- > Michael Opdenacker, Bootlin > Embedded Linux and Kernel engineering > https://bootlin.com > ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [docs] [PATCH 1/1] YP overview manual: style improvements 2021-03-31 15:39 ` Khem Raj @ 2021-04-02 12:47 ` Michael Opdenacker [not found] ` <16720B54D46DA7C3.28438@lists.yoctoproject.org> 1 sibling, 0 replies; 9+ messages in thread From: Michael Opdenacker @ 2021-04-02 12:47 UTC (permalink / raw) To: Khem Raj; +Cc: michael.opdenacker, docs Hi Khem, On 3/31/21 5:39 PM, Khem Raj wrote: > the left and right margins, how do they look on epub readers for this > document was > what I was wondering. Understood. Actually, the output is almost perfect and there are no side margins. That's great to read the text. It's just some of the diagrams that would be easier to read if they were rendered in full width. I'll see if there's something I can do and will keep you posted. Cheers, Michael. -- Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com ^ permalink raw reply [flat|nested] 9+ messages in thread
[parent not found: <16720B54D46DA7C3.28438@lists.yoctoproject.org>]
* Re: [docs] [PATCH 1/1] YP overview manual: style improvements [not found] ` <16720B54D46DA7C3.28438@lists.yoctoproject.org> @ 2021-04-02 14:10 ` Michael Opdenacker 2021-04-02 17:23 ` Khem Raj 0 siblings, 1 reply; 9+ messages in thread From: Michael Opdenacker @ 2021-04-02 14:10 UTC (permalink / raw) To: Khem Raj; +Cc: docs On 4/2/21 2:47 PM, Michael Opdenacker wrote: > Hi Khem, > > On 3/31/21 5:39 PM, Khem Raj wrote: >> the left and right margins, how do they look on epub readers for this >> document was >> what I was wondering. > > Understood. Actually, the output is almost perfect and there are no side > margins. That's great to read the text. > It's just some of the diagrams that would be easier to read if they were > rendered in full width. > > I'll see if there's something I can do and will keep you posted. By the way, don't hesitate to try by yourself (testers are welcome!) sudo apt install fbreader (or any ebook reader, if you're using Debian / Ubuntu) cd yocto-docs/documentation make epub fbreader _build/epub/TheYoctoProject.epub Cheers, Michael. -- Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [docs] [PATCH 1/1] YP overview manual: style improvements 2021-04-02 14:10 ` Michael Opdenacker @ 2021-04-02 17:23 ` Khem Raj 2021-04-06 20:10 ` Michael Opdenacker 0 siblings, 1 reply; 9+ messages in thread From: Khem Raj @ 2021-04-02 17:23 UTC (permalink / raw) To: Michael Opdenacker; +Cc: docs Hi Michael Yes send me a link to epub I would like to put it on my kobo On Fri, Apr 2, 2021 at 7:10 AM Michael Opdenacker <michael.opdenacker@bootlin.com> wrote: > > > On 4/2/21 2:47 PM, Michael Opdenacker wrote: > > Hi Khem, > > > > On 3/31/21 5:39 PM, Khem Raj wrote: > >> the left and right margins, how do they look on epub readers for this > >> document was > >> what I was wondering. > > > > Understood. Actually, the output is almost perfect and there are no side > > margins. That's great to read the text. > > It's just some of the diagrams that would be easier to read if they were > > rendered in full width. > > > > I'll see if there's something I can do and will keep you posted. > > By the way, don't hesitate to try by yourself (testers are welcome!) > > sudo apt install fbreader (or any ebook reader, if you're using Debian / > Ubuntu) > > cd yocto-docs/documentation > make epub > fbreader _build/epub/TheYoctoProject.epub > > Cheers, > > Michael. > > -- > Michael Opdenacker, Bootlin > Embedded Linux and Kernel engineering > https://bootlin.com > ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [docs] [PATCH 1/1] YP overview manual: style improvements 2021-04-02 17:23 ` Khem Raj @ 2021-04-06 20:10 ` Michael Opdenacker 0 siblings, 0 replies; 9+ messages in thread From: Michael Opdenacker @ 2021-04-06 20:10 UTC (permalink / raw) To: Khem Raj; +Cc: docs Hi Khem, On 4/2/21 7:23 PM, Khem Raj wrote: > Hi Michael > > Yes send me a link to epub I would like to put it on my kobo Sure, I have a Kobo too: https://bootlin.com/~mike/pub/yocto-project/TheYoctoProject-20210330.epub Cheers, Michael. -- Michael Opdenacker, Bootlin Embedded Linux and Kernel engineering https://bootlin.com ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2021-04-06 20:10 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-03-30 15:19 [PATCH 0/1] YP overview manual: style improvements Michael Opdenacker
2021-03-30 15:19 ` [PATCH 1/1] " Michael Opdenacker
2021-03-30 19:50 ` [docs] " Khem Raj
2021-03-31 9:14 ` Michael Opdenacker
2021-03-31 15:39 ` Khem Raj
2021-04-02 12:47 ` Michael Opdenacker
[not found] ` <16720B54D46DA7C3.28438@lists.yoctoproject.org>
2021-04-02 14:10 ` Michael Opdenacker
2021-04-02 17:23 ` Khem Raj
2021-04-06 20:10 ` Michael Opdenacker
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.