[PATCH] docs: escape literal asterisk to fix reST emphasis warning

[PATCH] docs: escape literal asterisk to fix reST emphasis warning

[Khaled Elnaggar]

Escaped a literal '*' character in symbol-namespaces.rst to prevent
a Docutils warning about unmatched emphasis markers during documentation build.

Signed-off-by: Khaled Elnaggar <khaledelnaggarlinux@gmail.com>
---

Hello, this is probably too trivial to have its own patch, but I found
it while building today's tag, so I thought I would send a patch.

---
 Documentation/core-api/symbol-namespaces.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/core-api/symbol-namespaces.rst b/Documentation/core-api/symbol-namespaces.rst
index f7cfa7b73e97..008b34fe6629 100644
--- a/Documentation/core-api/symbol-namespaces.rst
+++ b/Documentation/core-api/symbol-namespaces.rst
@@ -87,7 +87,7 @@ modules to access this symbol. Simple tail-globs are supported.

 For example:

-  EXPORT_SYMBOL_GPL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-*")
+  EXPORT_SYMBOL_GPL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-\*")

 will limit usage of this symbol to modules whoes name matches the given
 patterns.
--
2.47.2

Re: [PATCH] docs: escape literal asterisk to fix reST emphasis warning

[Matthew Wilcox]

On Mon, May 26, 2025 at 09:43:59PM +0300, Khaled Elnaggar wrote:
> Escaped a literal '*' character in symbol-namespaces.rst to prevent
> a Docutils warning about unmatched emphasis markers during documentation build.

I don't think this is the right way to fix this problem.  We want
the test to work in both rendered and un-rendered form.  I think
we can do something like:

-For example:
+For example::

to turn it into a block that is rendered literally.  See

                For example::

                  echo $((100 * `cat active_duration` / `cat connected_duration`))

as an example in Documentation/ABI/stable/sysfs-bus-usb

>  For example:
> 
> -  EXPORT_SYMBOL_GPL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-*")
> +  EXPORT_SYMBOL_GPL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-\*")
> 
>  will limit usage of this symbol to modules whoes name matches the given
>  patterns.
> --
> 2.47.2
> 
> 

Re: [PATCH] docs: escape literal asterisk to fix reST emphasis warning

[Khaled Elnaggar]

On 26/05/2025 10:35 pm, Matthew Wilcox wrote:
> On Mon, May 26, 2025 at 09:43:59PM +0300, Khaled Elnaggar wrote:
>> Escaped a literal '*' character in symbol-namespaces.rst to prevent
>> a Docutils warning about unmatched emphasis markers during documentation build.
> 
> I don't think this is the right way to fix this problem.  We want
> the test to work in both rendered and un-rendered form.  I think
> we can do something like:
> 
> -For example:
> +For example::
> 
> to turn it into a block that is rendered literally.  See
> 
>                 For example::
> 
>                   echo $((100 * `cat active_duration` / `cat connected_duration`))
> 
> as an example in Documentation/ABI/stable/sysfs-bus-usb
> 
>>  For example:
>>
>> -  EXPORT_SYMBOL_GPL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-*")
>> +  EXPORT_SYMBOL_GPL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-\*")
>>
>>  will limit usage of this symbol to modules whoes name matches the given
>>  patterns.
>> --
>> 2.47.2
>>
>>

That even looks better in rendered, (::) are actually so prevalent I don't know
how I did not see it before. I will send v2, thank you for the proper fix.

[PATCH v2] docs: symbol-namespaces: fix reST warning with literal block

[Khaled Elnaggar]

Use a literal block for the EXPORT_SYMBOL_GPL_FOR_MODULES() example to
avoid a Docutils warning about unmatched '*'. This ensures correct rendering
and keeps the source readable.

Warning:
Documentation/core-api/symbol-namespaces.rst:90: WARNING: Inline emphasis start-string without end-string. [docutils]

Signed-off-by: Khaled Elnaggar <khaledelnaggarlinux@gmail.com>
---

Changes in v2:
- Use 'For example::' to create a literal block, suggested by Matthew Wilcox.

---
 Documentation/core-api/symbol-namespaces.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/core-api/symbol-namespaces.rst b/Documentation/core-api/symbol-namespaces.rst
index f7cfa7b73e97..32fc73dc5529 100644
--- a/Documentation/core-api/symbol-namespaces.rst
+++ b/Documentation/core-api/symbol-namespaces.rst
@@ -85,7 +85,7 @@ namespace cannot be imported.
 The macro takes a comma separated list of module names, allowing only those
 modules to access this symbol. Simple tail-globs are supported.

-For example:
+For example::

   EXPORT_SYMBOL_GPL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-*")

--
2.47.2

Re: [PATCH v2] docs: symbol-namespaces: fix reST warning with literal block

[Bagas Sanjaya]

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

On Tue, May 27, 2025 at 12:10:39AM +0300, Khaled Elnaggar wrote:
> diff --git a/Documentation/core-api/symbol-namespaces.rst b/Documentation/core-api/symbol-namespaces.rst
> index f7cfa7b73e97..32fc73dc5529 100644
> --- a/Documentation/core-api/symbol-namespaces.rst
> +++ b/Documentation/core-api/symbol-namespaces.rst
> @@ -85,7 +85,7 @@ namespace cannot be imported.
>  The macro takes a comma separated list of module names, allowing only those
>  modules to access this symbol. Simple tail-globs are supported.
> 
> -For example:
> +For example::
> 
>    EXPORT_SYMBOL_GPL_FOR_MODULES(preempt_notifier_inc, "kvm,kvm-*")
> 
 
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 v2] docs: symbol-namespaces: fix reST warning with literal block

[Masahiro Yamada]

On Tue, May 27, 2025 at 6:10 AM Khaled Elnaggar
<khaledelnaggarlinux@gmail.com> wrote:
>
> Use a literal block for the EXPORT_SYMBOL_GPL_FOR_MODULES() example to
> avoid a Docutils warning about unmatched '*'. This ensures correct rendering
> and keeps the source readable.
>
> Warning:
> Documentation/core-api/symbol-namespaces.rst:90: WARNING: Inline emphasis start-string without end-string. [docutils]
>
> Signed-off-by: Khaled Elnaggar <khaledelnaggarlinux@gmail.com>
> ---
>
> Changes in v2:
> - Use 'For example::' to create a literal block, suggested by Matthew Wilcox.
>
> --



Applied to linux-kbuild.
Thanks.

-- 
Best Regards
Masahiro Yamada