Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Jonathan Corbet <corbet@lwn.net>
To:     Benjamin Gray <bgray@linux.ibm.com>, linux-kernel@vger.kernel.org,
        linux-ia64@vger.kernel.org, linux-doc@vger.kernel.org,
        bpf@vger.kernel.org, linux-pm@vger.kernel.org
Cc:     abbotti@mev.co.uk, hsweeten@visionengravers.com,
        jan.kiszka@siemens.com, kbingham@kernel.org, mykolal@fb.com,
        Benjamin Gray <bgray@linux.ibm.com>
Subject: Re: [PATCH 2/8] Documentation/sphinx: fix Python string escapes
In-Reply-To: <20230814060704.79655-3-bgray@linux.ibm.com>
References: <20230814060704.79655-1-bgray@linux.ibm.com>
 <20230814060704.79655-3-bgray@linux.ibm.com>
Date:   Mon, 14 Aug 2023 07:35:57 -0600
Message-ID: <87jztxwxtu.fsf@meer.lwn.net>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

Benjamin Gray <bgray@linux.ibm.com> writes:

> Python 3.6 introduced a DeprecationWarning for invalid escape sequences.
> This is upgraded to a SyntaxWarning in Python 3.12, and will eventually
> be a syntax error.
>
> Fix these now to get ahead of it before it's an error.
>
> Signed-off-by: Benjamin Gray <bgray@linux.ibm.com>
> ---
>  Documentation/sphinx/cdomain.py             | 2 +-
>  Documentation/sphinx/kernel_abi.py          | 2 +-
>  Documentation/sphinx/kernel_feat.py         | 2 +-
>  Documentation/sphinx/kerneldoc.py           | 2 +-
>  Documentation/sphinx/maintainers_include.py | 8 ++++----
>  5 files changed, 8 insertions(+), 8 deletions(-)

So I am the maintainer for this stuff...is there a reason you didn't
copy me on this work?

> diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
> index ca8ac9e59ded..dbdc74bd0772 100644
> --- a/Documentation/sphinx/cdomain.py
> +++ b/Documentation/sphinx/cdomain.py
> @@ -93,7 +93,7 @@ def markup_ctype_refs(match):
>  #
>  RE_expr = re.compile(r':c:(expr|texpr):`([^\`]+)`')
>  def markup_c_expr(match):
> -    return '\ ``' + match.group(2) + '``\ '
> +    return '\\ ``' + match.group(2) + '``\\ '

I have to wonder about this one; I doubt the intent was to insert a
literal backslash.  I have to fire up my ancient build environment to
even try this, but even if it's right...

>  #
>  # Parse Sphinx 3.x C markups, replacing them by backward-compatible ones
> diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
> index b5feb5b1d905..b9f026f016fd 100644
> --- a/Documentation/sphinx/kernel_abi.py
> +++ b/Documentation/sphinx/kernel_abi.py
> @@ -138,7 +138,7 @@ class KernelCmd(Directive):
>                  code_block += "\n    " + l
>              lines = code_block + "\n\n"
>  
> -        line_regex = re.compile("^\.\. LINENO (\S+)\#([0-9]+)$")
> +        line_regex = re.compile("^\\.\\. LINENO (\\S+)\\#([0-9]+)$")

All of these really just want to be raw strings - a much more minimal
fix that makes the result quite a bit more readable:

     line_regex = re.compile(r"^\.\. LINENO (\S+)\#([0-9]+)$")
                             ^
                             |
  ---------------------------+

That, I think, is how these should be fixed.

Thanks,

jon