[RFC PATCH] Documentation: doc-guide: fixes to sphinx.rst

[RFC PATCH] Documentation: doc-guide: fixes to sphinx.rst

[Randy Dunlap]

Various fixes to sphinx.rst:

- eliminate a double-space between 2 words
- grammar/wording
- punctuation
- call rows in a table 'rows' instead of 'columns' (or does Sphinx
  call everything a column?)
- It seems that "amdfonts" should be "amsfonts". I can't find any
  amdfonts.


Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
---
 Documentation/doc-guide/sphinx.rst |   32 +++++++++++++--------------
 1 file changed, 16 insertions(+), 16 deletions(-)

--- lnx-511-rc1.orig/Documentation/doc-guide/sphinx.rst
+++ lnx-511-rc1/Documentation/doc-guide/sphinx.rst
@@ -48,12 +48,12 @@ or ``virtualenv``, depending on how your
       those versions, you should run ``pip install 'docutils==0.12'``.
 
    #) It is recommended to use the RTD theme for html output. Depending
-      on the Sphinx version, it should be installed  in separate,
+      on the Sphinx version, it should be installed separately,
       with ``pip install sphinx_rtd_theme``.
 
-   #) Some ReST pages contain math expressions. Due to the way Sphinx work,
+   #) Some ReST pages contain math expressions. Due to the way Sphinx works,
       those expressions are written using LaTeX notation. It needs texlive
-      installed with amdfonts and amsmath in order to evaluate them.
+      installed with amsfonts and amsmath in order to evaluate them.
 
 In summary, if you want to install Sphinx version 1.7.9, you should do::
 
@@ -128,7 +128,7 @@ Sphinx Build
 ============
 
 The usual way to generate the documentation is to run ``make htmldocs`` or
-``make pdfdocs``. There are also other formats available, see the documentation
+``make pdfdocs``. There are also other formats available: see the documentation
 section of ``make help``. The generated documentation is placed in
 format-specific subdirectories under ``Documentation/output``.
 
@@ -303,17 +303,17 @@ and *targets* (e.g. a ref to ``:ref:`las
         - head col 3
         - head col 4
 
-      * - column 1
+      * - row 1
         - field 1.1
         - field 1.2 with autospan
 
-      * - column 2
+      * - row 2
         - field 2.1
         - :rspan:`1` :cspan:`1` field 2.2 - 3.3
 
       * .. _`last row`:
 
-        - column 3
+        - row 3
 
 Rendered as:
 
@@ -325,17 +325,17 @@ Rendered as:
         - head col 3
         - head col 4
 
-      * - column 1
+      * - row 1
         - field 1.1
         - field 1.2 with autospan
 
-      * - column 2
+      * - row 2
         - field 2.1
         - :rspan:`1` :cspan:`1` field 2.2 - 3.3
 
       * .. _`last row`:
 
-        - column 3
+        - row 3
 
 Cross-referencing
 -----------------
@@ -361,7 +361,7 @@ Figures & Images
 
 If you want to add an image, you should use the ``kernel-figure`` and
 ``kernel-image`` directives. E.g. to insert a figure with a scalable
-image format use SVG (:ref:`svg_image_example`)::
+image format, use SVG (:ref:`svg_image_example`)::
 
     .. kernel-figure::  svg_image.svg
        :alt:    simple SVG image
@@ -375,7 +375,7 @@ image format use SVG (:ref:`svg_image_ex
 
    SVG image example
 
-The kernel figure (and image) directive support **DOT** formatted files, see
+The kernel figure (and image) directive supports **DOT** formatted files, see
 
 * DOT: http://graphviz.org/pdf/dotguide.pdf
 * Graphviz: http://www.graphviz.org/content/dot-language
@@ -394,7 +394,7 @@ A simple example (:ref:`hello_dot_file`)
 
    DOT's hello world example
 
-Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
+Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
 ``kernel-render`` directives.::
 
   .. kernel-render:: DOT
@@ -406,7 +406,7 @@ Embed *render* markups (or languages) li
      }
 
 How this will be rendered depends on the installed tools. If Graphviz is
-installed, you will see an vector image. If not the raw markup is inserted as
+installed, you will see a vector image. If not, the raw markup is inserted as
 *literal-block* (:ref:`hello_dot_render`).
 
 .. _hello_dot_render:
@@ -421,8 +421,8 @@ installed, you will see an vector image.
 
 The *render* directive has all the options known from the *figure* directive,
 plus option ``caption``.  If ``caption`` has a value, a *figure* node is
-inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
-you want to refer it (:ref:`hello_svg_render`).
+inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
+you want to refer to it (:ref:`hello_svg_render`).
 
 Embedded **SVG**::
 

Re: [RFC PATCH] Documentation: doc-guide: fixes to sphinx.rst

[Mauro Carvalho Chehab]

Em Mon, 28 Dec 2020 15:12:12 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Various fixes to sphinx.rst:
> 
> - eliminate a double-space between 2 words
> - grammar/wording
> - punctuation
> - call rows in a table 'rows' instead of 'columns' (or does Sphinx
>   call everything a column?)
> - It seems that "amdfonts" should be "amsfonts". I can't find any
>   amdfonts.
> 
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Regards,
Mauro


> ---
>  Documentation/doc-guide/sphinx.rst |   32 +++++++++++++--------------
>  1 file changed, 16 insertions(+), 16 deletions(-)
> 
> --- lnx-511-rc1.orig/Documentation/doc-guide/sphinx.rst
> +++ lnx-511-rc1/Documentation/doc-guide/sphinx.rst
> @@ -48,12 +48,12 @@ or ``virtualenv``, depending on how your
>        those versions, you should run ``pip install 'docutils==0.12'``.
>  
>     #) It is recommended to use the RTD theme for html output. Depending
> -      on the Sphinx version, it should be installed  in separate,
> +      on the Sphinx version, it should be installed separately,
>        with ``pip install sphinx_rtd_theme``.
>  
> -   #) Some ReST pages contain math expressions. Due to the way Sphinx work,
> +   #) Some ReST pages contain math expressions. Due to the way Sphinx works,
>        those expressions are written using LaTeX notation. It needs texlive
> -      installed with amdfonts and amsmath in order to evaluate them.
> +      installed with amsfonts and amsmath in order to evaluate them.
>  
>  In summary, if you want to install Sphinx version 1.7.9, you should do::
>  
> @@ -128,7 +128,7 @@ Sphinx Build
>  ============
>  
>  The usual way to generate the documentation is to run ``make htmldocs`` or
> -``make pdfdocs``. There are also other formats available, see the documentation
> +``make pdfdocs``. There are also other formats available: see the documentation
>  section of ``make help``. The generated documentation is placed in
>  format-specific subdirectories under ``Documentation/output``.
>  
> @@ -303,17 +303,17 @@ and *targets* (e.g. a ref to ``:ref:`las
>          - head col 3
>          - head col 4
>  
> -      * - column 1
> +      * - row 1
>          - field 1.1
>          - field 1.2 with autospan
>  
> -      * - column 2
> +      * - row 2
>          - field 2.1
>          - :rspan:`1` :cspan:`1` field 2.2 - 3.3
>  
>        * .. _`last row`:
>  
> -        - column 3
> +        - row 3
>  
>  Rendered as:
>  
> @@ -325,17 +325,17 @@ Rendered as:
>          - head col 3
>          - head col 4
>  
> -      * - column 1
> +      * - row 1
>          - field 1.1
>          - field 1.2 with autospan
>  
> -      * - column 2
> +      * - row 2
>          - field 2.1
>          - :rspan:`1` :cspan:`1` field 2.2 - 3.3
>  
>        * .. _`last row`:
>  
> -        - column 3
> +        - row 3
>  
>  Cross-referencing
>  -----------------
> @@ -361,7 +361,7 @@ Figures & Images
>  
>  If you want to add an image, you should use the ``kernel-figure`` and
>  ``kernel-image`` directives. E.g. to insert a figure with a scalable
> -image format use SVG (:ref:`svg_image_example`)::
> +image format, use SVG (:ref:`svg_image_example`)::
>  
>      .. kernel-figure::  svg_image.svg
>         :alt:    simple SVG image
> @@ -375,7 +375,7 @@ image format use SVG (:ref:`svg_image_ex
>  
>     SVG image example
>  
> -The kernel figure (and image) directive support **DOT** formatted files, see
> +The kernel figure (and image) directive supports **DOT** formatted files, see
>  
>  * DOT: http://graphviz.org/pdf/dotguide.pdf
>  * Graphviz: http://www.graphviz.org/content/dot-language
> @@ -394,7 +394,7 @@ A simple example (:ref:`hello_dot_file`)
>  
>     DOT's hello world example
>  
> -Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the
> +Embedded *render* markups (or languages) like Graphviz's **DOT** are provided by the
>  ``kernel-render`` directives.::
>  
>    .. kernel-render:: DOT
> @@ -406,7 +406,7 @@ Embed *render* markups (or languages) li
>       }
>  
>  How this will be rendered depends on the installed tools. If Graphviz is
> -installed, you will see an vector image. If not the raw markup is inserted as
> +installed, you will see a vector image. If not, the raw markup is inserted as
>  *literal-block* (:ref:`hello_dot_render`).
>  
>  .. _hello_dot_render:
> @@ -421,8 +421,8 @@ installed, you will see an vector image.
>  
>  The *render* directive has all the options known from the *figure* directive,
>  plus option ``caption``.  If ``caption`` has a value, a *figure* node is
> -inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if
> -you want to refer it (:ref:`hello_svg_render`).
> +inserted. If not, an *image* node is inserted. A ``caption`` is also needed, if
> +you want to refer to it (:ref:`hello_svg_render`).
>  
>  Embedded **SVG**::
>  



Thanks,
Mauro

Re: [RFC PATCH] Documentation: doc-guide: fixes to sphinx.rst

[Jonathan Corbet]

On Mon, 28 Dec 2020 15:12:12 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> Various fixes to sphinx.rst:
> 
> - eliminate a double-space between 2 words
> - grammar/wording
> - punctuation
> - call rows in a table 'rows' instead of 'columns' (or does Sphinx
>   call everything a column?)
> - It seems that "amdfonts" should be "amsfonts". I can't find any
>   amdfonts.

Applied, thanks.

jon