On Fri, 05 Apr 2019, Matthew Wilcox <willy@xxxxxxxxxxxxx> 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
