On Fri, 5 Apr 2019 14:18:20 -0700 Sean Christopherson <sean.j.christopherson@xxxxxxxxx> 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. So I'm sympathetic toward the goal; we want this stuff to format properly. But I'm less convinced about this specific solution. Starting with the details: > -my $type_constant2 = '\%([-_\w]+)'; > +my $type_constant2 = '(^|[^\`\\\])\%([-_\w]+)'; This only escapes the % if it occurs *immediately* after the backtick, so something like ``foo %p`` will still get processed incorrectly. Somebody will surely run into that at some point and waste a bunch of time trying to figure out what's going on. Also, believe it or not, I don't think you have enough backslashes; that inner expression, I believe, should be: [^\`\\\\] Gosh Perl regexes are fun... This highlights the danger of adding functionality that isn't exercised anywhere; I don't think it works here. Now to more general considerations. Willy's suggestion of using %% instead makes some sense, though it may lead to pushback from the "no extra markup ever" contingent. It should be more straightforward to implement correctly. I have to wonder if the % thing is actually buying us much, honestly. It's another form of markup that kind of duplicates the Sphinx notation, and we've kind of agreed that most of the time, we don't want to clutter our text with ``explicit markup`` like that. I'm curious what people think: might the best solution be to just make %const do nothing special, with the idea of phasing it out? Thanks, jon
