[PATCH] doc: fix three-dash references in reStructuredText

[PATCH] doc: fix three-dash references in reStructuredText

[Grzegorz Szymaszek]

The "Sending patches" and "Patman patch manager" documents refer to the
three-dash, "---", that separates patch parts. The symbol is written in
the documentation in the same form as it is in actual patches: as three
U+002D HYPHEN-MINUS characters. When building the documentation, Sphinx
converts this symbol to a U+2014 EM DASH, that is invalid in this case.

Make the three-dash symbol a reStructuredText inline literal to prevent
its conversion; that is, enclose it in a pair of double backquotes (`).

Signed-off-by: Grzegorz Szymaszek <gszymaszek@short.pl>
---
 doc/develop/sending_patches.rst | 4 ++--
 tools/patman/patman.rst         | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
index 5a6962f102..3f25b1d046 100644
--- a/doc/develop/sending_patches.rst
+++ b/doc/develop/sending_patches.rst
@@ -121,7 +121,7 @@ General Patch Submission Rules
    * For new features: a description of the feature and your implementation.
 
 * Additional comments which you don't want included in U-Boot's history can be
-  included below the first "---" in the message body.
+  included below the first "``---``" in the message body.
 
 * If your description gets too long, that's a strong indication that you should
   split up your patch.
@@ -253,7 +253,7 @@ to observe the following rules.
 
 * Please make sure to keep a "change log", i.e. a description of what you have
   changed compared to previous versions of this patch. This change log should
-  be added below the "---" line in the patch, which starts the "comment
+  be added below the "``---``" line in the patch, which starts the "comment
   section", i.e. which contains text that does not get included into the
   actual commit message.
   Note: it is *not* sufficient to provide a change log in some cover letter
diff --git a/tools/patman/patman.rst b/tools/patman/patman.rst
index a8b317eed6..e01355824c 100644
--- a/tools/patman/patman.rst
+++ b/tools/patman/patman.rst
@@ -280,7 +280,7 @@ Series-notes:
 
 Commit-notes:
     Similar, but for a single commit (patch). These notes will appear
-    immediately below the --- cut in the patch file::
+    immediately below the ``---`` cut in the patch file::
 
         Commit-notes:
         blah blah
-- 
2.43.0

Re: [PATCH] doc: fix three-dash references in reStructuredText

[Mattijs Korpershoek]

Hi Grzegorz,

Thank you for the patch.

On sam., janv. 06, 2024 at 11:36, Grzegorz Szymaszek <gszymaszek@short.pl> wrote:

> The "Sending patches" and "Patman patch manager" documents refer to the
> three-dash, "---", that separates patch parts. The symbol is written in
> the documentation in the same form as it is in actual patches: as three
> U+002D HYPHEN-MINUS characters. When building the documentation, Sphinx
> converts this symbol to a U+2014 EM DASH, that is invalid in this case.
>
> Make the three-dash symbol a reStructuredText inline literal to prevent
> its conversion; that is, enclose it in a pair of double backquotes (`).
>
> Signed-off-by: Grzegorz Szymaszek <gszymaszek@short.pl>

Reviewed-by: Mattijs Korpershoek <mkorpershoek@baylibre.com>

> ---
>  doc/develop/sending_patches.rst | 4 ++--
>  tools/patman/patman.rst         | 2 +-
>  2 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
> index 5a6962f102..3f25b1d046 100644
> --- a/doc/develop/sending_patches.rst
> +++ b/doc/develop/sending_patches.rst
> @@ -121,7 +121,7 @@ General Patch Submission Rules
>     * For new features: a description of the feature and your implementation.
>  
>  * Additional comments which you don't want included in U-Boot's history can be
> -  included below the first "---" in the message body.
> +  included below the first "``---``" in the message body.
>  
>  * If your description gets too long, that's a strong indication that you should
>    split up your patch.
> @@ -253,7 +253,7 @@ to observe the following rules.
>  
>  * Please make sure to keep a "change log", i.e. a description of what you have
>    changed compared to previous versions of this patch. This change log should
> -  be added below the "---" line in the patch, which starts the "comment
> +  be added below the "``---``" line in the patch, which starts the "comment
>    section", i.e. which contains text that does not get included into the
>    actual commit message.
>    Note: it is *not* sufficient to provide a change log in some cover letter
> diff --git a/tools/patman/patman.rst b/tools/patman/patman.rst
> index a8b317eed6..e01355824c 100644
> --- a/tools/patman/patman.rst
> +++ b/tools/patman/patman.rst
> @@ -280,7 +280,7 @@ Series-notes:
>  
>  Commit-notes:
>      Similar, but for a single commit (patch). These notes will appear
> -    immediately below the --- cut in the patch file::
> +    immediately below the ``---`` cut in the patch file::
>  
>          Commit-notes:
>          blah blah
> -- 
> 2.43.0