Re: [PATCH 1/8] docs: kernel-doc: Get rid of xml_escape() and friends

[Jani Nikula <jani.nikula@linux.intel.com>]

On Wed, 07 Feb 2018, Jonathan Corbet <corbet@lwn.net> 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 <corbet@lwn.net>
> ---
>  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/\</\\\\\\lt;/g;
> -	$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;/</g;
> -	$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:/</g;
> -	$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