[Issue] sphinx: incorrect high-lighting

[Issue] sphinx: incorrect high-lighting

[Manuel Ebner]

I think in the documentation is some incorrect auto high-lighting.

https://docs.kernel.org/process/deprecated.html

Line 272:
> when such a struct was in unions, structs of structs, etc).
with 'struct was' bold.

Line 358:
> alone in a struct or is part of a union. These are disallowed by the C99
with 'struct or' bold as well.

Other files have the same issue:
E.g.: https://docs.kernel.org/process/adding-syscalls.html

Unfortunately I don't know how to fix this.

Thanks
 Manuel

Re: [Issue] sphinx: incorrect high-lighting

[Weijie Yuan]

On Sun, Aug 23, 2026 at 05:14:20PM +0200, Manuel Ebner wrote:
> I think in the documentation is some incorrect auto high-lighting.
> 
> https://docs.kernel.org/process/deprecated.html
> 
> Line 272:
> > when such a struct was in unions, structs of structs, etc).
> with 'struct was' bold.
> 
> Line 358:
> > alone in a struct or is part of a union. These are disallowed by the C99
> with 'struct or' bold as well.
> 
> Other files have the same issue:
> E.g.: https://docs.kernel.org/process/adding-syscalls.html
> 
> Unfortunately I don't know how to fix this.

Hi Manuel,

I think we can just add "or" and "was" to Skipidentifiers, so that it
won't be treated as C identifiers.

--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -51,7 +51,7 @@ Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]
 # when following struct/union/enum/typedef keywords.
 # Example: "a simple struct that" in workqueue.rst should not be marked as code.
 #
-Skipidentifiers = [ 'that', 'which', 'where', 'whose' ]
+Skipidentifiers = [ 'or', 'that', 'was', 'which', 'where', 'whose' ]
 
 #
 # Many places in the docs refer to common system calls.  It is

But I find more words needs to be added when looking at
process/adding-syscalls.rst. Adding the falsely highlighted words one by
one may not be a perfect solution, since it could potentially affect
other places where those words should actually be highlighted. So I'm
not quite sure what the best approach is either now.

Thanks.

Re: [Issue] sphinx: incorrect high-lighting

[Manuel Ebner]

On Sun, 2026-08-23 at 23:57 +0800, Weijie Yuan wrote:
> On Sun, Aug 23, 2026 at 05:14:20PM +0200, Manuel Ebner wrote:
> > I think in the documentation is some incorrect auto high-lighting.
> > 
> > https://docs.kernel.org/process/deprecated.html
> > 
> > Line 272:
> > > when such a struct was in unions, structs of structs, etc).
> > with 'struct was' bold.
> > 
> > Line 358:
> > > alone in a struct or is part of a union. These are disallowed by the C99
> > with 'struct or' bold as well.
> > 
> > Other files have the same issue:
> > E.g.: https://docs.kernel.org/process/adding-syscalls.html
> > 
> > Unfortunately I don't know how to fix this.
> 
> Hi Manuel,
> 
> I think we can just add "or" and "was" to Skipidentifiers, so that it
> won't be treated as C identifiers.
> 
> --- a/Documentation/sphinx/automarkup.py
> +++ b/Documentation/sphinx/automarkup.py
> @@ -51,7 +51,7 @@ Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]
>  # when following struct/union/enum/typedef keywords.
>  # Example: "a simple struct that" in workqueue.rst should not be marked as code.
>  #
> -Skipidentifiers = [ 'that', 'which', 'where', 'whose' ]
> +Skipidentifiers = [ 'or', 'that', 'was', 'which', 'where', 'whose' ]
>  
>  #
>  # Many places in the docs refer to common system calls.  It is
> 
> But I find more words needs to be added when looking at
> process/adding-syscalls.rst. 

It would be this list:
Skipidentifiers = [ 'and', 'are', 'as', 'containing', 'element', 'in',
                    'including', 'is', 'name', 'needs', 'of', 'or',  'page',
                    'pages', 'passed', 'randomization', 'request', 'that',
                    'to', 'where', 'which', 'whose', 'will' ]

> Adding the falsely highlighted words one by
> one may not be a perfect solution, since it could potentially affect
> other places where those words should actually be highlighted. So I'm
> not quite sure what the best approach is either now.

Me neither.

Thanks
 Manuel

> Thanks.

Re: [Issue] sphinx: incorrect high-lighting

[Randy Dunlap]

On 8/23/26 11:08 AM, Manuel Ebner wrote:
> On Sun, 2026-08-23 at 23:57 +0800, Weijie Yuan wrote:
>> On Sun, Aug 23, 2026 at 05:14:20PM +0200, Manuel Ebner wrote:
>>> I think in the documentation is some incorrect auto high-lighting.
>>>
>>> https://docs.kernel.org/process/deprecated.html
>>>
>>> Line 272:
>>>> when such a struct was in unions, structs of structs, etc).
>>> with 'struct was' bold.
>>>
>>> Line 358:
>>>> alone in a struct or is part of a union. These are disallowed by the C99
>>> with 'struct or' bold as well.
>>>
>>> Other files have the same issue:
>>> E.g.: https://docs.kernel.org/process/adding-syscalls.html
>>>
>>> Unfortunately I don't know how to fix this.
>>
>> Hi Manuel,
>>
>> I think we can just add "or" and "was" to Skipidentifiers, so that it
>> won't be treated as C identifiers.
>>
>> --- a/Documentation/sphinx/automarkup.py
>> +++ b/Documentation/sphinx/automarkup.py
>> @@ -51,7 +51,7 @@ Skipnames = [ 'for', 'if', 'register', 'sizeof', 'struct', 'unsigned' ]
>>  # when following struct/union/enum/typedef keywords.
>>  # Example: "a simple struct that" in workqueue.rst should not be marked as code.
>>  #
>> -Skipidentifiers = [ 'that', 'which', 'where', 'whose' ]
>> +Skipidentifiers = [ 'or', 'that', 'was', 'which', 'where', 'whose' ]
>>  
>>  #
>>  # Many places in the docs refer to common system calls.  It is
>>
>> But I find more words needs to be added when looking at
>> process/adding-syscalls.rst. 
> 
> It would be this list:
> Skipidentifiers = [ 'and', 'are', 'as', 'containing', 'element', 'in',
>                     'including', 'is', 'name', 'needs', 'of', 'or',  'page',
>                     'pages', 'passed', 'randomization', 'request', 'that',
>                     'to', 'where', 'which', 'whose', 'will' ]

We have a struct page, so this would interfere with it being
highlighted correctly, I guess.

Oh, and there is a struct element (not currently used as
kernel-doc).

>> Adding the falsely highlighted words one by
>> one may not be a perfect solution, since it could potentially affect
>> other places where those words should actually be highlighted. So I'm
>> not quite sure what the best approach is either now.
> 
> Me neither.
> 
> Thanks
>  Manuel
> 
>> Thanks.
> 

-- 
~Randy

Re: [Issue] sphinx: incorrect high-lighting

[Jonathan Corbet]

Manuel Ebner <manuelebnerli@mailbox.org> writes:

> It would be this list:
> Skipidentifiers = [ 'and', 'are', 'as', 'containing', 'element', 'in',
>                     'including', 'is', 'name', 'needs', 'of', 'or',  'page',
>                     'pages', 'passed', 'randomization', 'request', 'that',
>                     'to', 'where', 'which', 'whose', 'will' ]

So this is an error-prone game of whac-a-mole...as Randy pointed out,
"struct page" is a rather important one in the kernel.

I can apply your updated version of this as a short-term fix, I guess,
but a better solution is probably to only apply markup to "struct foo"
if we have documentation for that type.  I can look into that later.

jon