[PATCH] kbuild: Documentation: clean up makefiles.rst

[PATCH] kbuild: Documentation: clean up makefiles.rst

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

This is a general cleanup of kbuild/makefiles.rst:

* Use "Chapter" for major heading references and use "section" for
  the next-level heading references, for consistency.
* Section 3.8 was deleted long ago.
* Drop the ending ':' in section names in the contents list.
* Correct some section numbering references.
* Correct verb agreement typo.
* Fix run-on sentence punctuation.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Masahiro Yamada <masahiroy@kernel.org>
Cc: Michal Marek <michal.lkml@markovi.net>
Cc: linux-kbuild@vger.kernel.org
---
 Documentation/kbuild/makefiles.rst |   18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

--- linux-next-20200828.orig/Documentation/kbuild/makefiles.rst
+++ linux-next-20200828/Documentation/kbuild/makefiles.rst
@@ -16,7 +16,7 @@ This document describes the Linux kernel
 	   --- 3.5 Library file goals - lib-y
 	   --- 3.6 Descending down in directories
 	   --- 3.7 Compilation flags
-	   --- 3.8 Command line dependency
+	   --- 3.8 <deleted>
 	   --- 3.9 Dependency tracking
 	   --- 3.10 Special Rules
 	   --- 3.11 $(CC) support functions
@@ -39,8 +39,8 @@ This document describes the Linux kernel
 
 	=== 7 Architecture Makefiles
 	   --- 7.1 Set variables to tweak the build to the architecture
-	   --- 7.2 Add prerequisites to archheaders:
-	   --- 7.3 Add prerequisites to archprepare:
+	   --- 7.2 Add prerequisites to archheaders
+	   --- 7.3 Add prerequisites to archprepare
 	   --- 7.4 List directories to visit when descending
 	   --- 7.5 Architecture-specific boot images
 	   --- 7.6 Building non-kbuild targets
@@ -129,7 +129,7 @@ The preferred name for the kbuild files
 be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
 file will be used.
 
-Section 3.1 "Goal definitions" is a quick intro, further chapters provide
+Section 3.1 "Goal definitions" is a quick intro; further chapters provide
 more details, with real examples.
 
 3.1 Goal definitions
@@ -965,7 +965,7 @@ When kbuild executes, the following step
 		KBUILD_LDFLAGS         := -m elf_s390
 
 	Note: ldflags-y can be used to further customise
-	the flags used. See chapter 3.7.
+	the flags used. See section 3.7.
 
     LDFLAGS_vmlinux
 	Options for $(LD) when linking vmlinux
@@ -1121,7 +1121,7 @@ When kbuild executes, the following step
 
 	In this example, the file target maketools will be processed
 	before descending down in the subdirectories.
-	See also chapter XXX-TODO that describe how kbuild supports
+	See also chapter XXX-TODO that describes how kbuild supports
 	generating offset header files.
 
 
@@ -1261,7 +1261,7 @@ When kbuild executes, the following step
 	always be built.
 	Assignments to $(targets) are without $(obj)/ prefix.
 	if_changed may be used in conjunction with custom commands as
-	defined in 6.8 "Custom kbuild commands".
+	defined in 7.8 "Custom kbuild commands".
 
 	Note: It is a typical mistake to forget the FORCE prerequisite.
 	Another common pitfall is that whitespace is sometimes
@@ -1411,7 +1411,7 @@ When kbuild executes, the following step
 	that may be shared between individual architectures.
 	The recommended approach how to use a generic header file is
 	to list the file in the Kbuild file.
-	See "7.2 generic-y" for further info on syntax etc.
+	See "8.2 generic-y" for further info on syntax etc.
 
 7.11 Post-link pass
 -------------------
@@ -1601,4 +1601,4 @@ is the right choice.
 
 - Describe how kbuild supports shipped files with _shipped.
 - Generating offset header files.
-- Add more variables to section 7?
+- Add more variables to chapters 7 or 9?

Re: [PATCH] kbuild: Documentation: clean up makefiles.rst

[Masahiro Yamada]

On Sat, Aug 29, 2020 at 2:26 AM Randy Dunlap <rdunlap@infradead.org> wrote:
>
> From: Randy Dunlap <rdunlap@infradead.org>
>
> This is a general cleanup of kbuild/makefiles.rst:
>
> * Use "Chapter" for major heading references and use "section" for
>   the next-level heading references, for consistency.
> * Section 3.8 was deleted long ago.
> * Drop the ending ':' in section names in the contents list.
> * Correct some section numbering references.
> * Correct verb agreement typo.
> * Fix run-on sentence punctuation.
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Masahiro Yamada <masahiroy@kernel.org>
> Cc: Michal Marek <michal.lkml@markovi.net>
> Cc: linux-kbuild@vger.kernel.org


Applied to linux-kbuild/fixes.
Thanks.


> ---
>  Documentation/kbuild/makefiles.rst |   18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
>
> --- linux-next-20200828.orig/Documentation/kbuild/makefiles.rst
> +++ linux-next-20200828/Documentation/kbuild/makefiles.rst
> @@ -16,7 +16,7 @@ This document describes the Linux kernel
>            --- 3.5 Library file goals - lib-y
>            --- 3.6 Descending down in directories
>            --- 3.7 Compilation flags
> -          --- 3.8 Command line dependency
> +          --- 3.8 <deleted>
>            --- 3.9 Dependency tracking
>            --- 3.10 Special Rules
>            --- 3.11 $(CC) support functions
> @@ -39,8 +39,8 @@ This document describes the Linux kernel
>
>         === 7 Architecture Makefiles
>            --- 7.1 Set variables to tweak the build to the architecture
> -          --- 7.2 Add prerequisites to archheaders:
> -          --- 7.3 Add prerequisites to archprepare:
> +          --- 7.2 Add prerequisites to archheaders
> +          --- 7.3 Add prerequisites to archprepare
>            --- 7.4 List directories to visit when descending
>            --- 7.5 Architecture-specific boot images
>            --- 7.6 Building non-kbuild targets
> @@ -129,7 +129,7 @@ The preferred name for the kbuild files
>  be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
>  file will be used.
>
> -Section 3.1 "Goal definitions" is a quick intro, further chapters provide
> +Section 3.1 "Goal definitions" is a quick intro; further chapters provide
>  more details, with real examples.
>
>  3.1 Goal definitions
> @@ -965,7 +965,7 @@ When kbuild executes, the following step
>                 KBUILD_LDFLAGS         := -m elf_s390
>
>         Note: ldflags-y can be used to further customise
> -       the flags used. See chapter 3.7.
> +       the flags used. See section 3.7.
>
>      LDFLAGS_vmlinux
>         Options for $(LD) when linking vmlinux
> @@ -1121,7 +1121,7 @@ When kbuild executes, the following step
>
>         In this example, the file target maketools will be processed
>         before descending down in the subdirectories.
> -       See also chapter XXX-TODO that describe how kbuild supports
> +       See also chapter XXX-TODO that describes how kbuild supports
>         generating offset header files.
>
>
> @@ -1261,7 +1261,7 @@ When kbuild executes, the following step
>         always be built.
>         Assignments to $(targets) are without $(obj)/ prefix.
>         if_changed may be used in conjunction with custom commands as
> -       defined in 6.8 "Custom kbuild commands".
> +       defined in 7.8 "Custom kbuild commands".
>
>         Note: It is a typical mistake to forget the FORCE prerequisite.
>         Another common pitfall is that whitespace is sometimes
> @@ -1411,7 +1411,7 @@ When kbuild executes, the following step
>         that may be shared between individual architectures.
>         The recommended approach how to use a generic header file is
>         to list the file in the Kbuild file.
> -       See "7.2 generic-y" for further info on syntax etc.
> +       See "8.2 generic-y" for further info on syntax etc.
>
>  7.11 Post-link pass
>  -------------------
> @@ -1601,4 +1601,4 @@ is the right choice.
>
>  - Describe how kbuild supports shipped files with _shipped.
>  - Generating offset header files.
> -- Add more variables to section 7?
> +- Add more variables to chapters 7 or 9?
>


-- 
Best Regards
Masahiro Yamada