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]

Message-ID: <20190408160314.05bc5ecb@lwn.net>
Date:   Mon, 8 Apr 2019 16:03:14 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Sean Christopherson <sean.j.christopherson@...el.com>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] kernel-doc: Let backtick and backslash escape percent
 sign

On Fri,  5 Apr 2019 14:18:20 -0700
Sean Christopherson <sean.j.christopherson@...el.com> 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