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

2018-02-14 Thread Jani Nikula 
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
>

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

2018-02-14 Thread Jonathan Corbet 
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 
---
 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/\/\\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;
-   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;
-   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($) {
#

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

2018-02-09 Thread Jonathan Corbet 
On Fri, 09 Feb 2018 11:09:27 +0200
Jani Nikula  wrote:

> 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!

See commit b05142675310 :)

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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

2018-02-09 Thread Jani Nikula 
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,

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

2018-02-07 Thread Jonathan Corbet 
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 
---
 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/\/\\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;
-   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;
-   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($) {
#