[PATCH] Documentation: multiple .rst files: Fix grammar and more consistent formatting

[PATCH] Documentation: multiple .rst files: Fix grammar and more consistent formatting

[Thorsten Blum]

sphinx.rst:
- remove unnecessary newline
- fix grammar s/check/checks
- capitalize heading "The C domain"

changes.rst:
- remove colon after "pahole" to be consistent with other entries

howto.rst:
- fix grammar s/you will/will you
- hyphenate "real-world problems"

Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com>
---
 Documentation/doc-guide/sphinx.rst | 7 +++----
 Documentation/process/changes.rst  | 4 ++--
 Documentation/process/howto.rst    | 4 ++--
 3 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 3d125fb4139d..2526811489bf 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -63,8 +63,7 @@ Image output
 ------------
 
 The kernel documentation build system contains an extension that
-handles images on both GraphViz and SVG formats (see
-:ref:`sphinx_kfigure`).
+handles images on both GraphViz and SVG formats (see :ref:`sphinx_kfigure`).
 
 For it to work, you need to install both GraphViz and ImageMagick
 packages. If those packages are not installed, the build system will
@@ -108,7 +107,7 @@ further info.
 Checking for Sphinx dependencies
 --------------------------------
 
-There's a script that automatically check for Sphinx dependencies. If it can
+There's a script that automatically checks for Sphinx dependencies. If it can
 recognize your distribution, it will also give a hint about the install
 command line options for your distro::
 
@@ -283,7 +282,7 @@ Here are some specific guidelines for the kernel documentation:
   from highlighting. For a short snippet of code embedded in the text, use \`\`.
 
 
-the C domain
+The C domain
 ------------
 
 The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 50b3d1cb1115..4c1552160321 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -144,8 +144,8 @@ Bison
 Since Linux 4.16, the build system generates parsers
 during build.  This requires bison 2.0 or later.
 
-pahole:
--------
+pahole
+------
 
 Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system
 generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index 6c73889c98fc..eebda4910a88 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -351,8 +351,8 @@ Managing bug reports
 --------------------
 
 One of the best ways to put into practice your hacking skills is by fixing
-bugs reported by other people. Not only you will help to make the kernel
-more stable, but you'll also learn to fix real world problems and you will
+bugs reported by other people. Not only will you help to make the kernel
+more stable, but you'll also learn to fix real-world problems and you will
 improve your skills, and other developers will be aware of your presence.
 Fixing bugs is one of the best ways to get merits among other developers,
 because not many people like wasting time fixing other people's bugs.
-- 
2.39.2

Re: [PATCH] Documentation: multiple .rst files: Fix grammar and more consistent formatting

[Randy Dunlap]

On 2/3/24 13:53, Thorsten Blum wrote:
> sphinx.rst:
> - remove unnecessary newline
> - fix grammar s/check/checks
> - capitalize heading "The C domain"
> 
> changes.rst:
> - remove colon after "pahole" to be consistent with other entries
> 
> howto.rst:
> - fix grammar s/you will/will you
> - hyphenate "real-world problems"
> 
> Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/doc-guide/sphinx.rst | 7 +++----
>  Documentation/process/changes.rst  | 4 ++--
>  Documentation/process/howto.rst    | 4 ++--
>  3 files changed, 7 insertions(+), 8 deletions(-)
> 

-- 
#Randy

Re: [PATCH] Documentation: multiple .rst files: Fix grammar and more consistent formatting

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 3048 bytes --]

On Sat, Feb 03, 2024 at 10:53:45PM +0100, Thorsten Blum wrote:
> diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
> index 3d125fb4139d..2526811489bf 100644
> --- a/Documentation/doc-guide/sphinx.rst
> +++ b/Documentation/doc-guide/sphinx.rst
> @@ -63,8 +63,7 @@ Image output
>  ------------
>  
>  The kernel documentation build system contains an extension that
> -handles images on both GraphViz and SVG formats (see
> -:ref:`sphinx_kfigure`).
> +handles images on both GraphViz and SVG formats (see :ref:`sphinx_kfigure`).
>  
>  For it to work, you need to install both GraphViz and ImageMagick
>  packages. If those packages are not installed, the build system will
> @@ -108,7 +107,7 @@ further info.
>  Checking for Sphinx dependencies
>  --------------------------------
>  
> -There's a script that automatically check for Sphinx dependencies. If it can
> +There's a script that automatically checks for Sphinx dependencies. If it can
>  recognize your distribution, it will also give a hint about the install
>  command line options for your distro::
>  
> @@ -283,7 +282,7 @@ Here are some specific guidelines for the kernel documentation:
>    from highlighting. For a short snippet of code embedded in the text, use \`\`.
>  
>  
> -the C domain
> +The C domain
>  ------------
>  
>  The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
> diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
> index 50b3d1cb1115..4c1552160321 100644
> --- a/Documentation/process/changes.rst
> +++ b/Documentation/process/changes.rst
> @@ -144,8 +144,8 @@ Bison
>  Since Linux 4.16, the build system generates parsers
>  during build.  This requires bison 2.0 or later.
>  
> -pahole:
> --------
> +pahole
> +------
>  
>  Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system
>  generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel
> diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
> index 6c73889c98fc..eebda4910a88 100644
> --- a/Documentation/process/howto.rst
> +++ b/Documentation/process/howto.rst
> @@ -351,8 +351,8 @@ Managing bug reports
>  --------------------
>  
>  One of the best ways to put into practice your hacking skills is by fixing
> -bugs reported by other people. Not only you will help to make the kernel
> -more stable, but you'll also learn to fix real world problems and you will
> +bugs reported by other people. Not only will you help to make the kernel
> +more stable, but you'll also learn to fix real-world problems and you will
>  improve your skills, and other developers will be aware of your presence.
>  Fixing bugs is one of the best ways to get merits among other developers,
>  because not many people like wasting time fixing other people's bugs.

LGTM, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] Documentation: multiple .rst files: Fix grammar and more consistent formatting

[Matthew Wilcox]

On Sat, Feb 03, 2024 at 10:53:45PM +0100, Thorsten Blum wrote:
> @@ -63,8 +63,7 @@ Image output
>  ------------
>  
>  The kernel documentation build system contains an extension that
> -handles images on both GraphViz and SVG formats (see
> -:ref:`sphinx_kfigure`).
> +handles images on both GraphViz and SVG formats (see :ref:`sphinx_kfigure`).

This should have been "in", not "on" in the original ... feel free to
fix that as a separate patch.  Or send a v2.  Whichever suits you better.

[PATCH v2] Documentation: multiple .rst files: Fix grammar and more consistent formatting

[Thorsten Blum]

sphinx.rst:
- Remove unnecessary newline
- Fix grammar s/on/in/
- Fix grammar s/check/checks/
- Capitalize heading "The C domain"

changes.rst:
- Remove colon after "pahole" to be consistent with other entries

howto.rst:
- Fix grammar s/you will/will you/
- Hyphenate "real-world problems"

Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Changes in v2:
- Preserve Reviewed-by: tags
- s/on/in/ in sphinx.rst as suggested by Matthew Wilcox <willy@infradead.org>
---
 Documentation/doc-guide/sphinx.rst | 7 +++----
 Documentation/process/changes.rst  | 4 ++--
 Documentation/process/howto.rst    | 4 ++--
 3 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 3d125fb4139d..709e19821a16 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -63,8 +63,7 @@ Image output
 ------------
 
 The kernel documentation build system contains an extension that
-handles images on both GraphViz and SVG formats (see
-:ref:`sphinx_kfigure`).
+handles images in both GraphViz and SVG formats (see :ref:`sphinx_kfigure`).
 
 For it to work, you need to install both GraphViz and ImageMagick
 packages. If those packages are not installed, the build system will
@@ -108,7 +107,7 @@ further info.
 Checking for Sphinx dependencies
 --------------------------------
 
-There's a script that automatically check for Sphinx dependencies. If it can
+There's a script that automatically checks for Sphinx dependencies. If it can
 recognize your distribution, it will also give a hint about the install
 command line options for your distro::
 
@@ -283,7 +282,7 @@ Here are some specific guidelines for the kernel documentation:
   from highlighting. For a short snippet of code embedded in the text, use \`\`.
 
 
-the C domain
+The C domain
 ------------
 
 The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 50b3d1cb1115..4c1552160321 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -144,8 +144,8 @@ Bison
 Since Linux 4.16, the build system generates parsers
 during build.  This requires bison 2.0 or later.
 
-pahole:
--------
+pahole
+------
 
 Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system
 generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index 6c73889c98fc..eebda4910a88 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -351,8 +351,8 @@ Managing bug reports
 --------------------
 
 One of the best ways to put into practice your hacking skills is by fixing
-bugs reported by other people. Not only you will help to make the kernel
-more stable, but you'll also learn to fix real world problems and you will
+bugs reported by other people. Not only will you help to make the kernel
+more stable, but you'll also learn to fix real-world problems and you will
 improve your skills, and other developers will be aware of your presence.
 Fixing bugs is one of the best ways to get merits among other developers,
 because not many people like wasting time fixing other people's bugs.
-- 
2.39.2

Re: [PATCH v2] Documentation: multiple .rst files: Fix grammar and more consistent formatting

[Jonathan Corbet]

Thorsten Blum <thorsten.blum@toblux.com> writes:

> sphinx.rst:
> - Remove unnecessary newline
> - Fix grammar s/on/in/
> - Fix grammar s/check/checks/
> - Capitalize heading "The C domain"
>
> changes.rst:
> - Remove colon after "pahole" to be consistent with other entries
>
> howto.rst:
> - Fix grammar s/you will/will you/
> - Hyphenate "real-world problems"
>
> Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
> Changes in v2:
> - Preserve Reviewed-by: tags
> - s/on/in/ in sphinx.rst as suggested by Matthew Wilcox <willy@infradead.org>
> ---
>  Documentation/doc-guide/sphinx.rst | 7 +++----
>  Documentation/process/changes.rst  | 4 ++--
>  Documentation/process/howto.rst    | 4 ++--
>  3 files changed, 7 insertions(+), 8 deletions(-)

Applied, thanks.

jon