linux-kernel - [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 for Android: free password hash cracker in your pocket

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

Message-Id: <20190405211820.17617-1-sean.j.christopherson@intel.com>
Date:   Fri,  5 Apr 2019 14:18:20 -0700
From:   Sean Christopherson <sean.j.christopherson@...el.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: [PATCH] kernel-doc: Let backtick and backslash escape percent sign

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.

Except for the aforementioned vsnprintf(), all .html output files from
`make htmldocs` are identical before and after this change.

Signed-off-by: Sean Christopherson <sean.j.christopherson@...el.com>
---
 scripts/kernel-doc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 3350e498b4ce..1890deb16725 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -210,7 +210,7 @@ my $anon_struct_union = 0;

 # match expressions used to find embedded type information
 my $type_constant = '\b``([^\`]+)``\b';
-my $type_constant2 = '\%([-_\w]+)';
+my $type_constant2 = '(^|[^\`\\\])\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
@@ -229,7 +229,7 @@ my $type_member_func = $type_member . '\(\)';
 # these are pretty rough
 my @highlights_man = (
                       [$type_constant, "\$1"],
-                      [$type_constant2, "\$1"],
+                      [$type_constant2, "\$1\$2"],
                       [$type_func, "\\\\fB\$1\\\\fP"],
                       [$type_enum, "\\\\fI\$1\\\\fP"],
                       [$type_struct, "\\\\fI\$1\\\\fP"],
@@ -244,7 +244,7 @@ my $blankline_man = "";
 # rst-mode
 my @highlights_rst = (
                        [$type_constant, "``\$1``"],
-                       [$type_constant2, "``\$1``"],
+                       [$type_constant2, "\$1``\$2``"],
                        # Note: need to escape () to avoid func matching later
                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
                        [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
-- 
2.21.0