Received: by 10.223.185.116 with SMTP id b49csp1068071wrg; Wed, 14 Feb 2018 11:06:11 -0800 (PST) X-Google-Smtp-Source: AH8x224CaPNENVc45g1mvV/wehyhX14ZTmkKbWm9/avRHFIjIW4EvxsDVaO9Rpp051NhnKfibxCc X-Received: by 10.98.134.206 with SMTP id x197mr84272pfd.172.1518635171027; Wed, 14 Feb 2018 11:06:11 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518635170; cv=none; d=google.com; s=arc-20160816; b=NxieQwvC00iz5Mbid4w9JOCeqXdplEdfwi+/rOu4iRtborsWYkMwjuDF8nRH59aLfT sHeHSnp2l/0Z/fcc3+gk2c8WKnQeYvK/kHdc8RLe75k3UPIqDMsuHqrw8b3/+it4pb7G VgohqhT1VB3IJFfTkv+08WXK7reEIbyIq+S1DOczz6Duoj9hZJRU8IOeG9HmUyZ/yQmR wWA/x/0X2VNN1QMdF0Wcgjbrcyig1Xa44Stws7TFwRvy9Uojl9Kx/ridMIXF97LJYyVw f4aBPl1VZcs4NNUlPwKaFQXuL7uLRkOVYND3TKvIn786hp1aRxoJySVwAxLk5hauMerV yoiQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:mime-version:message-id:date:references :organization:in-reply-to:subject:cc:to:from :arc-authentication-results; bh=maFVtK3/INrOhg2jbUcjTX8lelPEwYHeMQi1R6AoUUk=; b=0Zw1Afiqo13QSzp3gtQ5wIhx+DJ+gqRTjuvXaep161v4VjqrPcuYG2xO4n6jPjt+Zb KNMbm+p+Gxxl8wZwG37a9EAYMAwcAiK7naGjY0iW8pGT0LOnBZHMqPjF+7XHjRwkqF99 BOlwQFPjextBkcpLYP9q6lXQCLKz08UlBUtSvLbCP4mj8YNS8kYMtfvlsEDZmWV9GM4i 7QDUE8F3/vwYVhTjl3aR5B8AhuroM+CiLYkgo+G053/FIy5xAdMSvvIcoF3UJe6P0sUa SKg1oeiVJ1Wo1gG4axKhfh64VOmy3LyRJ90KgdTa0YwjB7xniYxZZMUotJireB978Wgn RtqQ== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id u1si2786852pgv.121.2018.02.14.11.05.53; Wed, 14 Feb 2018 11:06:10 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1162601AbeBNTE4 (ORCPT + 99 others); Wed, 14 Feb 2018 14:04:56 -0500 Received: from mga01.intel.com ([192.55.52.88]:56919 "EHLO mga01.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1162347AbeBNTEy (ORCPT ); Wed, 14 Feb 2018 14:04:54 -0500 X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by fmsmga101.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 14 Feb 2018 11:04:54 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,513,1511856000"; d="scan'208";a="30778730" Received: from rothache-mobl1.ger.corp.intel.com (HELO localhost) ([10.249.33.20]) by fmsmga001.fm.intel.com with ESMTP; 14 Feb 2018 11:04:51 -0800 From: Jani Nikula To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, Jonathan Corbet Subject: Re: [PATCH 1/8] docs: kernel-doc: Get rid of xml_escape() and friends In-Reply-To: <20180214184009.12657-2-corbet@lwn.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20180214184009.12657-1-corbet@lwn.net> <20180214184009.12657-2-corbet@lwn.net> Date: Wed, 14 Feb 2018 21:04:47 +0200 Message-ID: <878tbvjsts.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 14 Feb 2018, Jonathan Corbet wrote: > XML escaping is a worry that came with DocBook, which we no longer have any > dealings with. So get rid of the useless xml_escape()/xml_unescape() > functions. No change to the generated output. > > Signed-off-by: Jonathan Corbet Reviewed-by: Jani Nikula > --- > scripts/kernel-doc | 65 ++++++++---------------------------------------------- > 1 file changed, 9 insertions(+), 56 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index fee8952037b1..5aa4ce211fc6 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -553,10 +553,9 @@ sub output_highlight { > } > if ($line eq ""){ > if (! $output_preformatted) { > - print $lineprefix, local_unescape($blankline); > + print $lineprefix, $blankline; > } > } else { > - $line =~ s/\\\\\\/\&/g; > if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { > print "\\&$line"; > } else { > @@ -751,9 +750,6 @@ sub output_highlight_rst { > my $contents = join "\n",@_; > my $line; > > - # undo the evil effects of xml_escape() earlier > - $contents = xml_unescape($contents); > - > eval $dohighlight; > die $@ if $@; > > @@ -1422,8 +1418,6 @@ sub push_parameter($$$$) { > } > } > > - $param = xml_escape($param); > - > # strip spaces from $param so that it is one continuous string > # on @parameterlist; > # this fixes a problem where check_sections() cannot find > @@ -1748,47 +1742,6 @@ sub process_proto_type($$) { > } > } > > -# xml_escape: replace <, >, and & in the text stream; > -# > -# however, formatting controls that are generated internally/locally in the > -# kernel-doc script are not escaped here; instead, they begin life like > -# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings > -# are converted to their mnemonic-expected output, without the 4 * '\' & ':', > -# just before actual output; (this is done by local_unescape()) > -sub xml_escape($) { > - my $text = shift; > - if ($output_mode eq "man") { > - return $text; > - } > - $text =~ s/\&/\\\\\\amp;/g; > - $text =~ s/\ - $text =~ s/\>/\\\\\\gt;/g; > - return $text; > -} > - > -# xml_unescape: reverse the effects of xml_escape > -sub xml_unescape($) { > - my $text = shift; > - if ($output_mode eq "man") { > - return $text; > - } > - $text =~ s/\\\\\\amp;/\&/g; > - $text =~ s/\\\\\\lt;/ - $text =~ s/\\\\\\gt;/>/g; > - return $text; > -} > - > -# convert local escape strings to html > -# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes) > -sub local_unescape($) { > - my $text = shift; > - if ($output_mode eq "man") { > - return $text; > - } > - $text =~ s/\\\\\\\\lt:/ - $text =~ s/\\\\\\\\gt:/>/g; > - return $text; > -} > > sub map_filename($) { > my $file; > @@ -1889,7 +1842,7 @@ sub process_file($) { > $descr =~ s/^\s*//; > $descr =~ s/\s*$//; > $descr =~ s/\s+/ /g; > - $declaration_purpose = xml_escape($descr); > + $declaration_purpose = $descr; > $in_purpose = 1; > } else { > $declaration_purpose = ""; > @@ -1944,7 +1897,7 @@ sub process_file($) { > print STDERR "${file}:$.: warning: contents before sections\n"; > ++$warnings; > } > - dump_section($file, $section, xml_escape($contents)); > + dump_section($file, $section, $contents); > $section = $section_default; > } > > @@ -1962,7 +1915,7 @@ sub process_file($) { > $leading_space = undef; > } elsif (/$doc_end/) { > if (($contents ne "") && ($contents ne "\n")) { > - dump_section($file, $section, xml_escape($contents)); > + dump_section($file, $section, $contents); > $section = $section_default; > $contents = ""; > } > @@ -1981,7 +1934,7 @@ sub process_file($) { > # @parameter line to signify start of description > if ($1 eq "") { > if ($section =~ m/^@/ || $section eq $section_context) { > - dump_section($file, $section, xml_escape($contents)); > + dump_section($file, $section, $contents); > $section = $section_default; > $contents = ""; > $new_start_line = $.; > @@ -1992,7 +1945,7 @@ sub process_file($) { > } elsif ($in_purpose == 1) { > # Continued declaration purpose > chomp($declaration_purpose); > - $declaration_purpose .= " " . xml_escape($1); > + $declaration_purpose .= " " . $1; > $declaration_purpose =~ s/\s+/ /g; > } else { > my $cont = $1; > @@ -2030,7 +1983,7 @@ sub process_file($) { > # Documentation block end */ > } elsif (/$doc_inline_end/) { > if (($contents ne "") && ($contents ne "\n")) { > - dump_section($file, $section, xml_escape($contents)); > + dump_section($file, $section, $contents); > $section = $section_default; > $contents = ""; > } > @@ -2057,7 +2010,7 @@ sub process_file($) { > $contents = $2; > if ($contents ne "") { > $contents .= "\n"; > - dump_section($file, $section, xml_escape($contents)); > + dump_section($file, $section, $contents); > $section = $section_default; > $contents = ""; > } > @@ -2072,7 +2025,7 @@ sub process_file($) { > } elsif ($state == STATE_DOCBLOCK) { > if (/$doc_end/) > { > - dump_doc_section($file, $section, xml_escape($contents)); > + dump_doc_section($file, $section, $contents); > $section = $section_default; > $contents = ""; > $function = ""; -- Jani Nikula, Intel Open Source Technology Center