kbuild: Documentation: clean up makefiles.rst

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>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
This commit is contained in:
Randy Dunlap 2020-08-28 10:26:26 -07:00 committed by Masahiro Yamada
parent a73fbfce2c
commit b26ff488b5

View File

@ -16,7 +16,7 @@ This document describes the Linux kernel Makefiles.
--- 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 Makefiles.
=== 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 are 'Makefile' but 'Kbuild' can
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 steps are followed (roughly):
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 steps are followed (roughly):
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 steps are followed (roughly):
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 steps are followed (roughly):
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?