linux-kernel - Re: [PATCH] kernel-doc: Let backtick and backslash escape percent sign

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Mon, 08 Apr 2019 12:58:17 +0300
From:   Jani Nikula <jani.nikula@...ux.intel.com>
To:     Matthew Wilcox <willy@...radead.org>,
        Sean Christopherson <sean.j.christopherson@...el.com>
Cc:     Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH] kernel-doc: Let backtick and backslash escape percent sign

On Fri, 05 Apr 2019, Matthew Wilcox <willy@...radead.org> wrote:
> On Fri, Apr 05, 2019 at 02:18:20PM -0700, Sean Christopherson wrote:
>> There are a handful of instances where kernel doc comments want an
>> actual '%' in the final output, e.g. vsnprintf() wants to display "%n"
>> and "%p" to document format specifiers, and assembly functions that use
>> a custom call ABI may want to document their register usage, e.g. %eax.
>> 
>> Because kernel-doc unconditionally interprets '%' followed by a word
>> character as a constant definition, i.e. %CONST, it's impossible to get
>> an actual '%\w' when kernel-doc is used to translate comments into rst
>> format.  Treat backtick and backlash as escaping '%', the former to
>> handle '%' in a ``LITERAL``, and the latter to allow '%' when using
>> standard formatting.
>> 
>> An alternative option would be to define a fancier set of rules for
>> interpreting '%' so that explicit escaping would not be required.  For
>> example, require "%CONST" to be preceded by a recognized set of
>> characters, e.g. whitespace, opening parenthesis, etc...  But the list
>> of recognized characters is quite large even in the current code base,
>> and using '\' to escape is more common and intuitive, i.e. most people
>> will naturally try doing "\%..." to get the desired formatting, whereas
>> losing %CONST formatting because of an unrecognized character is likely
>> to cause confusion.
>
> Would it make sense to have %% turn into % rather than forcing quotation
> marks?

The problem is not limited to % though.

I see two long-term solutions to the problem:

1) Define proper escaping and quoting rules for kernel-doc to pass
   through stuff as-is to Sphinx. This may be difficult to implement
   because, well, see kernel-doc source.

2) Figure out how to do the kernel-doc references and highlights in the
   Sphinx extension after all the reStructuredText processing.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center