Documentation cleanup
cover Documentation cleanup
Hi,
Here is a series that fixes a few typoes and makes small improvements in documentation.
Regards,
Jerzy
Jerzy Grzegorek (9):
manual/configure.txt: reword part about internal toolchain backend manual/configure.txt: fix typo
manual/make-tips.txt: fix typo
manual/contribute.txt: fix typo
manual/contribute.txt: reword part about reporting issues manual/legal-notice.txt: fix typo manual/contribute.txt: reword part about versioning patches
manual: fix typo in abbreviation 'e.g.'
manual: fix typo in abbreviation 'i.e.'
docs/manual/adding-packages-autotools.txt | 2 +- docs/manual/adding-packages-generic.txt | 4 ++-- docs/manual/common-usage.txt | 8 ++++---- docs/manual/configure.txt | 16 ++++++++-------- docs/manual/contribute.txt | 8 +++++--- docs/manual/customize-outside-br.txt | 2 +- docs/manual/faq-troubleshooting.txt | 2 +- docs/manual/legal-notice.txt | 2 +- docs/manual/make-tips.txt | 2 +- 9 files changed, 24 insertions(+), 22 deletions(-)
Signature · 1 line
1.7.9.5
PATCH 1/9 manual/configure.txt: reword part about internal toolchain backend
--- docs/manual/configure.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
docs/manual/configure.txt +1 -1
@@ -100,7 +100,7 @@ most important ones allow to: toolchain should have largefile support (i.e support for files larger than 2 GB on 32 bits systems), IPv6 support, RPC support (used mainly for NFS), wide-char support, locale support (for - internationalization), C++ support, thread support. Depending on + internationalization), C++ support or thread support. Depending on which options you choose, the number of userspace applications and libraries visible in Buildroot menus will change: many applications and libraries require certain toolchain options to be enabled. Most
Signature · 1 line
1.7.9.5
PATCH 2/9 manual/configure.txt: fix typo
In reply to Jerzy Grzegorek--- docs/manual/configure.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
docs/manual/configure.txt +1 -1
@@ -165,7 +165,7 @@ Then, you have three solutions to use an external toolchain: prefix+ and +External toolchain C library+ options. Then, you have to tell Buildroot what your external toolchain supports. If your external toolchain uses the 'glibc' library, you only have to tell - whether your toolchain supports C\+\+ or not and whether it has + whether your toolchain supports C++ or not and whether it has built-in RPC support. If your external toolchain uses the 'uClibc' library, then you have to tell Buildroot if it supports largefile, IPv6, RPC, wide-char, locale, program invocation, threads and
Signature · 1 line
1.7.9.5
PATCH 2/9 manual/configure.txt: fix typo
Dear Jerzy Grzegorek,
Quoted 10 lines · Jerzy Grzegorek
Signed-off-by Jerzy Grzegorek <[email protected]>--- docs/manual/configure.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)docs/manual/configure.txt +0
-0
docs/manual/configure.txt Then, you have three solutions to use an external toolchain: · line 168
Quoted 5 lines
docs/manual/configure.txt +1
-1@@ -165,7 +165,7 @@ Then, you have three solutions to use an external toolchain: prefix+ and +External toolchain C library+ options. Then, you have to tell Buildroot what your external toolchain supports. If your external toolchain uses the 'glibc' library, you only have to tell - whether your toolchain supports C\+\+ or not and whether it has + whether your toolchain supports C++ or not and whether it has
Have you checked if the rendered files of the manual are still correct after this? IIRC, these backslashes were needed because ++ is a valid asciidoc construct.
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
PATCH 2/9 manual/configure.txt: fix typo
Hi Thomas,
Quoted 8 lines
Dear Jerzy Grzegorek,
Quoted 5 lines · Jerzy Grzegorek
Signed-off-by Jerzy Grzegorek <[email protected]>--- docs/manual/configure.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Quoted 13 lines
docs/manual/configure.txt Then, you have three solutions to use an external toolchain: · line 168
Quoted 10 lines
docs/manual/configure.txt +1
-1@@ -165,7 +165,7 @@ Then, you have three solutions to use an external toolchain: prefix+ and +External toolchain C library+ options. Then, you have to tell Buildroot what your external toolchain supports. If your external toolchain uses the 'glibc' library, you only have to tell - whether your toolchain supports C\+\+ or not and whether it has + whether your toolchain supports C++ or not and whether it hasHave you checked if the rendered files of the manual are still correct after this? IIRC, these backslashes were needed because ++ is a valid asciidoc construct.
Ah yes, right. I have removed one slash too much.
It should be: C\++
Thanks for reviewing.
Regards,
Jerzy
Quoted 2 lines
Thomas
PATCH 3/9 manual/make-tips.txt: fix typo
In reply to Jerzy Grzegorek--- docs/manual/make-tips.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
docs/manual/make-tips.txt +1 -1
@@ -32,7 +32,7 @@ The result of the search shows the help message of the matching items. Not all targets are always available, some settings in the +.config+ file may hide some targets: -* +busybox-menuconfig+ and +busybox-savedefconfig+ ony work when +* +busybox-menuconfig+ and +busybox-savedefconfig+ only work when +busybox+ is enabled; * +linux-menuconfig+ and +linux-savedefconfig+ only work when +linux+ is enabled;
Signature · 1 line
1.7.9.5
PATCH 4/9 manual/contribute.txt: fix typo
In reply to Jerzy Grzegorek--- docs/manual/contribute.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
docs/manual/contribute.txt +1 -1
@@ -97,7 +97,7 @@ To indicate approval of a patch, there are three formal tags that keep track of this approval. To add your tag to a patch, reply to it with the approval tag below the original author's Signed-off-by line. These tags will be picked up automatically by patchwork (see -ref:apply-patches-patchwork[]) and will be part of the commit log when +xref:apply-patches-patchwork[]) and will be part of the commit log when the patch is accepted. Tested-by:: Indicates that the patch has been tested successfully.
Signature · 1 line
1.7.9.5
PATCH 5/9 manual/contribute.txt: reword part about reporting issues
In reply to Jerzy Grzegorek--- docs/manual/contribute.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
docs/manual/contribute.txt +1 -1
@@ -307,7 +307,7 @@ Here is a short list of details to provide in such case: * any information you think that may be relevant Additionally, you should add the +.config+ file (or if you know how, a -+defconfig+). ++defconfig+; see xref:customize-store-buildroot-config[]). If some of these details are too large, do not hesitate to use a pastebin service. Note that not all available pastebin services will
Signature · 1 line
1.7.9.5
PATCH 6/9 manual/legal-notice.txt: fix typo
In reply to Jerzy Grzegorek--- docs/manual/legal-notice.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
docs/manual/legal-notice.txt +1 -1
@@ -99,7 +99,7 @@ Buildroot, with the name used in the manifest files: GNU Library General Public License, version 2]; * `LGPLv2+`: http://www.gnu.org/licenses/old-licenses/lgpl-2.0.html[ - GNU Library General Public License, version 2.1] + GNU Library General Public License, version 2] or (at your option) any later version; * `LGPLv2.1`: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html[
Signature · 1 line
1.7.9.5
PATCH 7/9 manual/contribute.txt: reword part about versioning patches
In reply to Jerzy Grzegorek--- docs/manual/contribute.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
docs/manual/contribute.txt +3 -1
@@ -270,7 +270,9 @@ Changes v1 -> v2: Any patch revision should include the version number. The version number is simply composed of the letter +v+ followed by an +integer+ greater or -equal to two (i.e. "PATCH v2", "PATCH v3" ...). +equal to two (i.e. "PATCH v2", "PATCH v3" ...). Note that when your patch +series is introduced by a cover letter, an overall patch version may be +added to the cover letter in addition/instead to the individual commits. This can be easily handled with +git format-patch+ by using the option +--subject-prefix+:
Signature · 1 line
1.7.9.5
PATCH 8/9 manual: fix typo in abbreviation 'e.g.'
In reply to Jerzy Grzegorek--- docs/manual/adding-packages-generic.txt | 4 ++-- docs/manual/common-usage.txt | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-)
docs/manual/adding-packages-generic.txt +2 -2
@@ -150,7 +150,7 @@ On line 31..33, we define a device-node file used by this package On line 35..37, we define the permissions to set to specific files installed by this package (+LIBFOO_PERMISSIONS+). -On lines 39..41, we define a user that is used by this package (eg. +On lines 39..41, we define a user that is used by this package (e.g. to run a daemon as non-root) (+LIBFOO_USERS+). Finally, on line 43, we call the +generic-package+ function, which
@@ -335,7 +335,7 @@ information is (assuming the package name is +libfoo+) : This variable is optional. * +LIBFOO_USERS+ lists the users to create for this package, if it installs - a program you want to run as a specific user (eg. as a daemon, or as a + a program you want to run as a specific user (e.g. as a daemon, or as a cron-job). The syntax is similar in spirit to the makedevs one, and is described in the xref:makeuser-syntax[]. This variable is optional.
docs/manual/common-usage.txt +4 -4
@@ -116,7 +116,7 @@ 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 -locations in the filesystems images may just be _empty_ (eg. a long run of +locations in the filesystems images may just be _empty_ (e.g. a long run of 'zeroes'); such a file is called a _sparse_ file. Most tools can handle sparse files efficiently, and will only store or write
@@ -139,12 +139,12 @@ For example: Other tools may have similar options. Please consult their respective man pages. -You can use sparse files if you need to store the filesystem images (eg. -to transfer from one machine to another), or if you need to send them (eg. +You can use sparse files if you need to store the filesystem images (e.g. +to transfer from one machine to another), or if you need to send them (e.g. to the Q&A team). Note however that flashing a filesystem image to a device while using the -sparse mode of +dd+ may result in a broken filesystem (eg. the block bitmap +sparse mode of +dd+ may result in a broken filesystem (e.g. the block bitmap of an ext2 filesystem may be corrupted; or, if you have sparse files in 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
Signature · 1 line
1.7.9.5
PATCH 9/9 manual: fix typo in abbreviation 'i.e.'
In reply to Jerzy Grzegorek--- docs/manual/adding-packages-autotools.txt | 2 +- docs/manual/configure.txt | 12 ++++++------ docs/manual/customize-outside-br.txt | 2 +- docs/manual/faq-troubleshooting.txt | 2 +- 4 files changed, 9 insertions(+), 9 deletions(-)
docs/manual/adding-packages-autotools.txt +1 -1
@@ -119,7 +119,7 @@ cases, typical packages will therefore only use a few of them. +make+ command. By default, empty. * +LIBFOO_AUTORECONF+, tells whether the package should - be autoreconfigured or not (i.e, if the configure script and + be autoreconfigured or not (i.e. if the configure script and Makefile.in files should be re-generated by re-running autoconf, automake, libtool, etc.). Valid values are +YES+ and +NO+. By default, the value is +NO+
docs/manual/configure.txt +6 -6
@@ -82,7 +82,7 @@ most important ones allow to: built. This library provides the interface between userspace applications and the Linux kernel. In order to know how to "talk" to the Linux kernel, the C library needs to have access to the - _Linux kernel headers_ (i.e, the +.h+ files from the kernel), which + _Linux kernel headers_ (i.e. the +.h+ files from the kernel), which define the interface between userspace and the kernel (system calls, data structures, etc.). Since this interface is backward compatible, the version of the Linux kernel headers used to build
@@ -97,7 +97,7 @@ most important ones allow to: * Change the version of the GCC compiler, binutils and the C library. * Select a number of toolchain options (uClibc only): whether the - toolchain should have largefile support (i.e support for files + toolchain should have largefile support (i.e. support for files larger than 2 GB on 32 bits systems), IPv6 support, RPC support (used mainly for NFS), wide-char support, locale support (for internationalization), C++ support or thread support. Depending on
@@ -180,17 +180,17 @@ Buildroot itself. In general, all toolchains that support the developers. We do not support toolchains or SDK generated by OpenEmbedded or -Yocto, because these toolchains are not pure toolchains (i.e just the +Yocto, because these toolchains are not pure toolchains (i.e. just the compiler, binutils, the C and C++ libraries). Instead these toolchains come with a very large set of pre-compiled libraries and programs. Therefore, Buildroot cannot import the 'sysroot' of the toolchain, as it would contain hundreds of megabytes of pre-compiled libraries that are normally built by Buildroot. -We also do not support using the distribution toolchain (i.e the +We also do not support using the distribution toolchain (i.e. the gcc/binutils/C library installed by your distribution) as the toolchain to build software for the target. This is because your -distribution toolchain is not a "pure" toolchain (i.e only with the +distribution toolchain is not a "pure" toolchain (i.e. only with the C/C++ library), so we cannot import it properly into the Buildroot build environment. So even if you are building a system for a x86 or x86_64 target, you have to generate a cross-compilation toolchain with
@@ -235,7 +235,7 @@ different solutions to handle the +/dev+ directory : * The first solution is *Static using device table*. This is the old classical way of handling device files in Linux. With this method, the device files are persistently stored in the root filesystem - (i.e they persist accross reboots), and there is nothing that will + (i.e. they persist accross reboots), and there is nothing that will automatically create and remove those device files when hardware devices are added or removed from the system. Buildroot therefore creates a standard set of device files using a _device table_, the
docs/manual/customize-outside-br.txt +1 -1
@@ -78,7 +78,7 @@ Or disable the usage of external definitions: directories called +board/<boardname>/+ under +BR2_EXTERNAL+. This matches the directory structure used within Buildroot. - * One can store package recipes (i.e +Config.in+ and + * One can store package recipes (i.e. +Config.in+ and +<packagename>.mk+), or even custom configuration options and make logic. Buildroot automatically includes +BR2_EXTERNAL/Config.in+ to make it appear in the top-level configuration menu, and includes
docs/manual/faq-troubleshooting.txt +1 -1
@@ -138,7 +138,7 @@ is much more complicated than that: * When a package is unselected from the configuration, it is not sufficient to remove just the files it installed. One must also - remove all its reverse dependencies (i.e packages relying on it) + remove all its reverse dependencies (i.e. packages relying on it) and rebuild all those packages. For example, package A depends optionally on the OpenSSL library. Both are selected, and Buildroot is built. Package A is built with crypto support using OpenSSL.
Signature · 1 line
1.7.9.5
cover Documentation cleanup
In reply to Jerzy GrzegorekDear Jerzy Grzegorek,
Quoted 2 lines · Jerzy Grzegorek
Here is a series that fixes a few typoes and makes small improvements in documentation.
I've applied patches 1 to 6, 8 and 9. For patch 2, I made the change we discussed.
I haven't applied patch 7, because I don't agree with:
+series is introduced by a cover letter, an overall patch version may be +added to the cover letter in addition/instead to the individual commits.
The version in the title of the cover letter does *not* replace the version in the title of the patches. Both should be present, so the "/instead" is not correct. Also, the "may be added" does not seem right, because a version is always added to the cover letter title by "git format-patch --subject-prefix".
Best regards,
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
cover Documentation cleanup
Hi Thomas,
Quoted 14 lines
Dear Jerzy Grzegorek,
Quoted 2 lines · Jerzy Grzegorek
Here is a series that fixes a few typoes and makes small improvements in documentation.
I've applied patches 1 to 6, 8 and 9. For patch 2, I made the change we discussed.
I haven't applied patch 7, because I don't agree with:
(quoted diff) +2
-0+series is introduced by a cover letter, an overall patch version may be +added to the cover letter in addition/instead to the individual commits.
Quoted 5 lines
The version in the title of the cover letter does *not* replace the version in the title of the patches. Both should be present, so the "/instead" is not correct. Also, the "may be added" does not seem right, because a version is always added to the cover letter title by "git format-patch --subject-prefix".
Regarding the "may be added", I agree.
I proposed this change because I saw on mailing list both cases of submitting patch series introduced by a cover letter:
* "in addition" case:
[Patch vX 0/Y] ...
[Patch vX 1/Y] ...
...
[Patch vX Y/Y] ...* "instead" case:
[Patch vX 0/Y] ...
[Patch 1/Y] ...
...
[Patch Y/Y] ...but ok, agree.
So maybe it should be:
"Note that when your patch series is introduced by a cover letter, a patch version should be added to the cover letter in addition to the individual commits."
Regards,
Jerzy
Quoted 4 lines
Best regards,
Thomas
cover Documentation cleanup
Dear Jerzy Grzegorek,
Quoted 10 lines · Jerzy Grzegorek
Regarding the "may be added", I agree.
I proposed this change because I saw on mailing list both cases of submitting patch series introduced by a cover letter:* "in addition" case:
[Patch vX 0/Y] ... [Patch vX 1/Y] ... ... [Patch vX Y/Y] ...
Quoted 5 lines
* "instead" case:
[Patch vX 0/Y] ... [Patch 1/Y] ... ... [Patch Y/Y] ...
To me, this second variant is wrong. This is because the cover letters are not recorded by patchwork, so if the version is not mentioned in the title of each individual patch, patchwork will not have the information of the version of the patches.
Quoted 4 lines
So maybe it should be:
"Note that when your patch series is introduced by a cover letter, a patch version should be added to the cover letter in addition to the individual commits."
But is it really necessary? Such a wording seems to imply that the contributor would have to do this manually, while the contributor should instead simply use "git format-patch --subject-prefix", which does just the right thing.
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
cover Documentation cleanup
Hi Thomas,
Quoted 24 lines
Dear Jerzy Grzegorek,
Quoted 10 lines · Jerzy Grzegorek
Regarding the "may be added", I agree.
I proposed this change because I saw on mailing list both cases of submitting patch series introduced by a cover letter:* "in addition" case: [Patch vX 0/Y] ... [Patch vX 1/Y] ... ... [Patch vX Y/Y] ...Quoted 5 lines
* "instead" case:
[Patch vX 0/Y] ... [Patch 1/Y] ... ... [Patch Y/Y] ...To me, this second variant is wrong. This is because the cover letters are not recorded by patchwork, so if the version is not mentioned in the title of each individual patch, patchwork will not have the information of the version of the patches.
Quoted 8 lines
Quoted 4 lines
So maybe it should be:
"Note that when your patch series is introduced by a cover letter, a patch version should be added to the cover letter in addition to the individual commits."But is it really necessary? Such a wording seems to imply that the contributor would have to do this manually, while the contributor should instead simply use "git format-patch --subject-prefix", which does just the right thing.
Ok, agree.
You haven't changed
C++ --> C\++
for my patch 2.
Regards,
Jerzy
Quoted 2 lines
Thomas
cover Documentation cleanup
Dear Jerzy Grzegorek,
Quoted 1 line · Jerzy Grzegorek
Ok, agree.
Ok, thanks!
Quoted 3 lines
You haven't changed
C++ --> C\++
for my patch 2.
Huh ? See
http://git.buildroot.net/buildroot/commit/?id=082dec8ce440236b1477e568f0965f05ad241adb
Thmas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
cover Documentation cleanup
Thomas, All,
On 2014-03-29 12:05 +0100, Thomas Petazzoni spake thusly:
Quoted 12 lines · Jerzy Grzegorek
Quoted 2 lines
Ok, agree.
Ok, thanks!
Quoted 3 lines
You haven't changed
C++ --> C\++
for my patch 2.Huh ? See
http://git.buildroot.net/buildroot/commit/?id=082dec8ce440236b1477e568f0965f05ad241adb
You missed one of the two changes.
Regards,
Yann E. MORIN.
Signature · 6 lines
.-----------------.--------------------.------------------.--------------------. | Yann E. MORIN | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: | | +33 662 376 056 | Software Designer | \ / CAMPAIGN | ___ | | +33 223 225 172 `------------.-------: X AGAINST | \e/ There is no | | http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL | v conspiracy. | '------------------------------^-------^------------------^--------------------'
cover Documentation cleanup
Dear Yann E. MORIN,
Quoted 8 lines · Yann E. MORIN
Quoted 6 lines
Quoted 3 lines
You haven't changed
C++ --> C\++
for my patch 2.Huh ? See
http://git.buildroot.net/buildroot/commit/?id=082dec8ce440236b1477e568f0965f05ad241adbYou missed one of the two changes.
Arghh, indeed.
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
cover Documentation cleanup
In reply to Thomas PetazzoniHi Thomas,
Quoted 4 lines
Dear Jerzy Grzegorek,
On Sat, 29 Mar 2014 11:59:26 +0100, Jerzy Grzegorek wrote:
Quoted 8 lines
Quoted 1 line
Ok, agree.
Ok, thanks!
Quoted 3 lines
You haven't changed
C++ --> C\++
for my patch 2.Huh ? See
http://git.buildroot.net/buildroot/commit/?id=082dec8ce440236b1477e568f0965f05ad241adb
My patach should change only
C\+\+ --> C\++
- whether your toolchain supports C\+\+ or not and whether it has
+ whether your toolchain supports C\++ or not and whether it has
Regards,
Jerzy
Quoted 2 lines
Thmas
cover Documentation cleanup
Dear Jerzy Grzegorek,
Quoted 19 lines · Jerzy Grzegorek
Hi Thomas,
Quoted 4 lines
Dear Jerzy Grzegorek,
On Sat, 29 Mar 2014 11:59:26 +0100, Jerzy Grzegorek wrote:
Quoted 8 lines
Quoted 1 line
Ok, agree.
Ok, thanks!
Quoted 3 lines
You haven't changed
C++ --> C\++
for my patch 2.Huh ? See
http://git.buildroot.net/buildroot/commit/?id=082dec8ce440236b1477e568f0965f05ad241adbMy patach should change only
C\+\+ --> C\++
Review
Quoted 2 lines
(quoted diff) +1
-1- whether your toolchain supports C\+\+ or not and whether it has + whether your toolchain supports C\++ or not and whether it has
I believe C++ should also be fixed to C\++, no?
In any case, can you send a corrective patch?
Thanks!
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Free Electrons Embedded Linux, Kernel and Android engineering http://free-electrons.com
cover Documentation cleanup
Hi Thomas,
Quoted 15 lines
Dear Jerzy Grzegorek,
Quoted 12 lines · Jerzy Grzegorek
Hi Thomas,
Quoted 10 lines
Dear Jerzy Grzegorek,
Quoted 1 line · Jerzy Grzegorek
Ok, agree.
Ok, thanks!
Quoted 3 lines
You haven't changed
C++ --> C\++
for my patch 2.
Quoted 8 lines
Review
Quoted 7 lines
Quoted 2 lines
Huh ? See
http://git.buildroot.net/buildroot/commit/?id=082dec8ce440236b1477e568f0965f05ad241adbMy patach should change only
C\+\+ --> C\++(quoted diff) +1
-1- whether your toolchain supports C\+\+ or not and whether it has + whether your toolchain supports C\++ or not and whether it hasI believe C++ should also be fixed to C\++, no?
No, only C\+\+ should be changed to C\++.
Quoted 2 lines
In any case, can you send a corrective patch?
Yes, of course.
Regards,
Jerzy
Quoted 4 lines
Thanks!
Thomas