Received: by 10.223.176.5 with SMTP id f5csp426918wra; Fri, 9 Feb 2018 01:10:41 -0800 (PST) X-Google-Smtp-Source: AH8x227efWfn047psceANKiwsm1aA3pP/dNaUaWghALt20wer8GK6dRWDxX3UIVlkKyyA6Q1RmCZ X-Received: by 10.101.90.8 with SMTP id y8mr1784112pgs.34.1518167441378; Fri, 09 Feb 2018 01:10:41 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518167441; cv=none; d=google.com; s=arc-20160816; b=UKyp35DwWpjz1dkg9UXAiF193qFZ14xk6vpxy/TEOde/BYdW2afrKXxx7GQPiNPz1g bXDPIeCA+ssVWwbnwSYCJNXUpDf8CZNDvcwRYnIzKhXyI7t4AsmfGMCyuHwd9O+fwEyw wzK8kCU/QtFMOEYbkJS+6FWQACWv4rMO3427axV1esvA9BtN7o91U9Lb2EWeVww13gTL xRZjFz9leekYorAAXdLZLK+Seo2gUKoAsRtWYEGc0AyngB9NWdlUcpMV+IOIvczcsZf9 gp/TuUazPfcu7n3seWrxJa4vGcB5ZayZYqMPXYC5g38ojLXsuayKFqrf3TT0A7pyFs2s 3gZg== 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=+ndCNawopVzUPzd19BnWiz+JKor6Y8RsQfqBpuOMZeQ=; b=O73VexSyJE/PAv+Ww/v9CdsshpppfRcNkqCP5FvXlg2gtrwX/NbHDWoLB+Vq1Von80 8mtVL6jylKmllJ0hxtqpC9nQ9N0yH2Lw8Ydkzl23/ZRd8Q0ZyyPrXb1O2NLq4bG2GhUP 758pvyqW6A2lsTaq7IfhmmmIJ/d4RE2bYDNtpYuFyJHWjKL/PPS7bCMYLSvV5UYb1FPO G0K0muR7IfZun5oJP9GSJmxYY/dotwlENbcouQdRhp9bx85zrGsk80eLgSjX+Iu1piRj DiX0RZfXsg6eibFi1h75CByZoODx7viwAxJH559SE9n5TZ5mtPlZbykEFWji3mKPZrAC 0ByQ== 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 h132si1416239pfe.169.2018.02.09.01.10.23; Fri, 09 Feb 2018 01:10:41 -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 S1750939AbeBIJJj (ORCPT + 99 others); Fri, 9 Feb 2018 04:09:39 -0500 Received: from mga03.intel.com ([134.134.136.65]:27033 "EHLO mga03.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750789AbeBIJJf (ORCPT ); Fri, 9 Feb 2018 04:09:35 -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 orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 09 Feb 2018 01:09:34 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,482,1511856000"; d="scan'208";a="29434595" Received: from jnikula-mobl2.fi.intel.com (HELO localhost) ([10.237.72.62]) by fmsmga001.fm.intel.com with ESMTP; 09 Feb 2018 01:09:31 -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: <20180207172624.24555-2-corbet@lwn.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20180207172624.24555-1-corbet@lwn.net> <20180207172624.24555-2-corbet@lwn.net> Date: Fri, 09 Feb 2018 11:09:27 +0200 Message-ID: <87inb6a5rs.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, 07 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. I think this will break at least the -docbook output option, perhaps also -html and -html5 options. If you think it's okay to break them, would it not be better to just axe those off first? I guess this boils down to, is kernel-doc the script a general purpose tool, or just a very specific part of the kernel documentation build process? FWIW I think the latter, and why don't you throw docbook/html support out already! BR, Jani. > > Signed-off-by: Jonathan Corbet > --- > 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