new version of help

1 files changed, 433 insertions, 127 deletions

diff --git a/scripts/fill_help_tables.sh b/scripts/fill_help_tables.sh
index e21b0ff2bb0..b8cf4ccb3a7 100644
--- a/scripts/fill_help_tables.sh
+++ b/scripts/fill_help_tables.sh
@@ -1,31 +1,178 @@
 #!@PERL@
 #
-# Usage: fill_help_tables <manual.texi>
-# Example: ./fill_help_tables < ../Docs/manual.texi > fill_help_tables.sql
+# Copyright (C) 2003 MySQL AB
+# For a more info consult the file COPYRIGHT distributed with this file.
 #
 # This script generates the SQL statements required by mysql_install_db to
 # fill up the tables for the server-side online function help, which can be
 # invoked with "help <function>" from the MySQL client.
 #
+# Usage:
+#   fill_help_tables OPTIONS  < manual.texi > fill_help_tables.sql
+#  
+#  --help           display this helpscreen and exit
+#  --verbose        print information about help completeness to STDERR
+#  --lexems=path    path to file with lexems. it is used with verbose option.
+#                       default value is ../sql/lex.h
+# Examples:
+#  ./fill_help_tables --help
+#  ./fill_help_tables --verbose < manual.texi > fill_help_tables.sql
+#  ./fill_help_tables < manual.texi > fill_help_tables.sql
+# 
 # Please note, that you first need to update Docs/manual.texi with the
 # manual file from the separate "mysqldoc" BitKeeper-Tree! The manual.texi
 # included in the source tree is just an empty stub file - the full manual
 # is now maintained in a separate tree.
 #
+# extra tags in manual.texi:
+#
+#	@c help_category <category_name>[@<parent_category_name>]
+#
+#	@c description_for_help_topic <topic_name>  <keyword1> <keyword2>
+#		....
+#	@c end_description_for_help_topic
+#
+#	@c example_for_help_topic <topic_name>
+#	@example
+#		....
+#	@example
+#
+#
 # Original version by Victor Vagin <vva@mysql.com>
 #
 
-my $cat_name= "";
-my $func_name= "";
-my $text= "";
-my $example= "";
+use strict;
+use Getopt::Long;
+
+my $insert_portion_size= 25;
+my $error_prefix= "help parsing error:";
+
+my $path_to_lex_file= "../sql/lex.h";
+my $verbose_option= 0;
+my $help_option= 0;
+
+GetOptions(
+  "help",\$help_option,
+  "verbose",\$verbose_option,
+  "lexems=s",\$path_to_lex_file
+);
+
+if ($help_option ne 0)
+{
+  print <<_HELP;
+
+This script generates the SQL statements required by mysql_install_db to
+fill up the tables for the server-side online function help, which can be
+invoked with "help <function>" from the MySQL client.
+
+Usage:
+  fill_help_tables OPTIONS  < manual.texi > fill_help_tables.sql
+  
+  --help           display this helpscreen and exit
+  --verbose        print information about help completeness to STDERR
+  --lexems=path    path to file with lexems. it is used with verbose option.
+                       default value is ../sql/lex.h
+
+Examples:
+  ./fill_help_tables --help
+  ./fill_help_tables --verbose < manual.texi > fill_help_tables.sql
+  ./fill_help_tables < manual.texi > fill_help_tables.sql
+    
+_HELP
+  exit;
+}
 
-local $mode= "";
+my $current_category= "";
+my $current_parent_category= "";
+my $next_example_for_topic= "";
+
+my %topics; 
+my %categories;
+my %keywords;
+
+$categories{Contents}->{__parent_category__}= "";
+
+sub add_topic_to_category
+{
+  my ($topic_name)= @_;
+
+  $categories{$current_category}->{$topic_name}= $topics{$topic_name};
+  my $category= $categories{$current_category};
+    
+  if (exists($category->{__parent_category__}))
+  {
+    my $old_parent= $category->{__parent_category__};
+    if ($old_parent ne $current_parent_category)
+    {
+      print STDERR "$error_prefix wrong parent for $current_category\n";
+    }
+  }
+
+  if ($current_parent_category ne "")
+  {
+    $category->{__parent_category__}= $current_parent_category;
+  }
+    
+  if (exists($topics{$topic_name}->{category}))
+  {
+    my $old_category= $topics{$topic_name}->{category};
+    if ($old_category ne $category)
+    {
+      print STDERR "$error_prefix wrong category for $topic_name\n";
+    }
+  }
+    
+  $topics{$topic_name}->{category}= $category;    
+}
+
+sub add_example
+{
+  my ($topic_name,$example)= @_;
+    
+  $topic_name=~ tr/a-z/A-Z/;
+
+  if (exists($topics{$topic_name}->{example}))
+  {
+    print STDERR "$error_prefix double example for $topic_name\n";
+  }
+    
+  $topics{$topic_name}->{example}= $example;    
+  add_topic_to_category($topic_name);
+}
+
+sub add_description
+{
+  my ($topic_name,$description)= @_;
+    
+  $topic_name=~ tr/a-z/A-Z/;
+    
+  if (exists($topics{$topic_name}->{description}))
+  {
+    print STDERR "$error_prefix double description for $topic_name\n";
+  }
+  $topics{$topic_name}->{description}= $description;
+  add_topic_to_category($topic_name);
+}
+
+sub add_keyword
+{
+  my ($topic_name,$keyword)= @_;
+    
+  $topic_name=~ tr/a-z/A-Z/;
+  $keyword=~ tr/a-z/A-Z/; 
+    
+  push(@{$topics{$topic_name}->{keywords}},$keyword);
+  if (exists($keywords{$keyword}->{$topic_name}))
+  {
+    print STDERR "$error_prefix double keyword $keyword for $topic_name\n";
+  }
+  $keywords{$keyword}->{$topic_name}= $topics{$topic_name};
+}
 
 sub prepare_name
 {
   my ($a)= @_;
-
+    
   $a =~ s/(\@itemize \@bullet)/  /g;
   $a =~ s/(\@end itemize)/  /g;
   $a =~ s/(\@end multitable)/  /g;
@@ -46,41 +193,57 @@ sub prepare_name
   $a =~ s/\`/\`\`/g;
 
   $a =~ s/\@table \@code/  /g;
-
   $a =~ s/\(\)//g;
-
-  $a =~ s/((\w|\s)+)\(([\+-=><\/%*!<>\s]+)\)/$3/gxs; #$a =~ s/((\w|\s)+)\(([\+-=><\/%*!<>\s]+)\)/$3 $1/gxs;
-  $a =~ s/([\+-=><\/%*!<>\s]+)\(((\w|\s)+)\)/$1/gxs;#$a =~ s/([\+-=><\/%*!<>\s]+)\(((\w|\s)+)\)/$1 $2/gxs;
+  $a =~ s/\"/\\\"/g;
+											
+  $a =~ s/((\w|\s)+)\(([\+-=><\/%*!<>\s]+)\)/$3/gxs;
+  $a =~ s/([\+-=><\/%*!<>\s]+)\(((\w|\s)+)\)/$1/gxs;
   $a =~ s/((\w|\s)+)\((.+)\)/$1/gxs;
-
+												    
   return $a;
 }
 
-sub prepare_text
+sub prepare_description
 {
   my ($a)= @_;
 
-  $a =~ s/(\@itemize \@bullet)/  /g;
-  $a =~ s/(\@end itemize)/  /g;
+  $a =~ s/(\@itemize \@bullet\n)//g;
+  $a =~ s/(\@c help_keyword (.*?)\n)//g;
+  $a =~ s/(\@end itemize\n)//g;
+  $a =~ s/(\@end example\n)//g;
+  $a =~ s/(\@example\n)//g;
+  $a =~ s/(\@{)/{/g;
+  $a =~ s/(\@})/}/g;
   $a =~ s/(\@end multitable)/  /g;
   $a =~ s/(\@end table)/  /g;
-  $a =~ s/(\@cindex(.*?)\n)/  /g;
+  $a =~ s/(\@cindex(.*?)\n)//g;
+  $a =~ s/(\@findex(.*?)\n)//g;
+  $a =~ s/(\@table(.*?)\n)//g;
   $a =~ s/(\@multitable \@columnfractions(.*?)\n)/  /g;
   $a =~ s/(\@node(.*?)\n)/  /g;
   $a =~ s/(\@tab)/\t/g;
   $a =~ s/\@itemx/  /g;
-  $a =~ s/\@item/  /g;
+  $a =~ s/(\@item\n(\s*?))(\S)/ --- $3/g;
+  $a =~ s/(\@item)/  /g;
+  $a =~ s/(\@tindex\s(.*?)\n)//g;
+  $a =~ s/(\@c\s(.*?)\n)//g;
   $a =~ s/\@code\{((.|\n)+?)\}/$1/go;
   $a =~ s/\@strong\{(.+?)\}/$1/go;
   $a =~ s/\@samp\{(.+?)\}/$1/go;
   $a =~ s/\@emph\{((.|\n)+?)\}/\/$1\//go;
   $a =~ s/\@xref\{((.|\n)+?)\}/See also : [$1]/go;
   $a =~ s/\@ref\{((.|\n)+?)\}/[$1]/go;
-  $a =~ s/\'/\'\'/g;
+  $a =~ s/\@w\{((.|\n)+?)\}/$1/go;
+  $a =~ s/\@strong\{((.|\n)+?)\}/\n!!!!\n$1\n!!!!\n/go;
+  $a =~ s/\@file\{((.|\n)+?)\}/\*$1/go;
   $a =~ s/\\/\\\\/g;
-  $a =~ s/\`/\`\`/g;
-  $a =~ s/(\n*?)$//g;
+  $a =~ s/\n\n$/\n/g;
+  $a =~ s/\n\n$/\n/g;
+  $a =~ s/\n\n$/\n/g;
+  $a =~ s/\n\n$/\n/g;
+  $a =~ s/\n\n$/\n/g;
   $a =~ s/\n/\\n/g;
+  $a =~ s/\"/\\\"/g;
 
   $a =~ s/\@table \@code/  /g;
 
@@ -91,148 +254,291 @@ sub prepare_example
 {
   my ($a)= @_;
 
-  $a =~ s/\'/\'\'/g;
+  $a =~ s/(^\@c for_help_topic(.*?)\n)//g;
+
   $a =~ s/\\/\\\\/g;
-  $a =~ s/\`/\`\`/g;
+  $a =~ s/(\@{)/{/g;
+  $a =~ s/(\@})/}/g;
+  $a =~ s/(\@\@)/\@/g;
   $a =~ s/(\n*?)$//g;
   $a =~ s/\n/\\n/g;
-
+  $a =~ s/\"/\\\"/g;
+    
   return $a;
 }
 
-sub flush_all
+sub parse_example
 {
-  my ($mode) = @_;
-
-  if ($mode eq ""){return;}
-
-  $func_name= prepare_name($func_name);
-  $text= prepare_text($text);
-  $example= prepare_example($example);
-
-  if ($func_name ne "" && $text ne "" && !($func_name =~ /[abcdefghikjlmnopqrstuvwxyz]/)){
-    print "INSERT IGNORE INTO help_topic (name,description,example) VALUES (";
-    print "'$func_name',";
-    print "'$text',";
-    print "'$example'";
-    print ");\n";
-    print "INSERT IGNORE INTO help_relation (help_category_id,help_topic_id) VALUES (\@cur_category,LAST_INSERT_ID());\n";
+  return if (!($_=~/\@example/));
+  return if ($next_example_for_topic eq "");
+    
+  my $topic_name= $next_example_for_topic;
+  $next_example_for_topic= "";
+  my $text= "";
+    
+  while (<>)
+  {
+    last if ($_=~/\@end example/);
+    $text .= $_;
   }
+    
+  $text= prepare_example($text);
 
-  $func_name= "";
-  $text= "";
-  $example= "";
-  $mode= "";
+  add_example($topic_name,$text) if ($topic_name ne "");
 }
 
-sub new_category
+sub parse_example_for_topic
 {
-  my ($category)= @_;
-
-  $category= prepare_text($category);
-
-  print "INSERT IGNORE INTO help_category (name) VALUES (\'$category\');\n";
-  print "SET \@cur_category=LAST_INSERT_ID();\n";
+  my ($for_topic)= m|\@c example_for_help_topic (.+?)$|;
+  return if ($for_topic eq "");
+    
+  $next_example_for_topic= $for_topic;    
 }
 
-#print "INSERT IGNORE INTO db (Host,DB,User,Select_priv) VALUES ('%','mysql_help','','Y');\n";
-#print "CREATE DATABASE mysql_help;\n";
+sub parse_description
+{
+  my ($topic_description)= m|\@c description_for_help_topic (.+?)$|;
+  return if ($topic_description eq "");
+    
+  my ($topic_name,$topic_keywords)= split(/  /,$topic_description);
+    
+  if ($topic_name eq "" || $topic_keywords eq "")
+  {
+    $topic_name= $topic_description;
+  }
+  else
+  {
+    my $keyword;
+    foreach $keyword (split(/ /,$topic_keywords))
+    {
+      add_keyword($topic_name,$keyword) if ($keyword ne "");
+    }
+  }
+    
+  my $text= "";
+    
+  while (<>)
+  {
+    last if ($_=~/\@c end_description_for_help_topic/);
+    $text .= $_;
+  }
+    
+  $text= prepare_description($text);
+  add_description($topic_name,$text);
+}
 
-print "USE mysql;\n";
+sub parse_category
+{
+  my ($c_name,$pc_name)= m|\@c help_category (.+?)\@(.+?)$|;
 
-print "DROP TABLE IF EXISTS help_topic;\n";
-print "CREATE TABLE help_topic (";
-print "  help_topic_id int unsigned not null auto_increment,";
-print "  name          varchar(64) not null,";
-print "  description   text not null,";
-print "  example       text not null,";
-print "  url           varchar(128) not null,";
-print "  primary key   (help_topic_id),";
-print "  unique index(name)";
-print ") type=myisam;\n\n";
+  if ($pc_name ne "")
+  {
+    $current_category= prepare_name($c_name);
+    $current_parent_category= prepare_name($pc_name);
+  }
+  else
+  {
+    my ($c_name)=m|\@c help_category (.+?)$|;
+    return if ($c_name eq "");
 
-print "DROP TABLE IF EXISTS help_category;\n";
-print "CREATE TABLE help_category (";
-print "  help_category_id smallint unsigned not null auto_increment,";
-print "  name             varchar(64) not null,";
-print "  url              varchar(128) not null,";
-print "  primary key      (help_category_id),";
-print "  unique index (name)";    
-print ") type=myisam;\n\n";
+    $current_category= prepare_name($c_name);
+    $current_parent_category= "Contents"
+  }
+}
 
-print "DROP TABLE IF EXISTS help_relation;\n";
-print "CREATE TABLE help_relation (";
-print"   help_topic_id    int unsigned not null references help_topic,";
-print"   help_category_id smallint unsigned not null references help_category,";
-print"   primary key      (help_category_id, help_topic_id),";
-print ") type=myisam;\n\n";
+# parse manual:
 
-print "SET \@cur_category=null;\n\n";
+while (<>)
+{
+  parse_example_for_topic ();
+  parse_example           ();
+  parse_description       ();	
+  parse_category          ();
+}
 
-my $in_section_6_3= 0;
+# test results of parsing:
 
-for(<>)
+sub print_bad_names
 {
-  if ($_=~/\@section Functions for Use in \@code{SELECT} and \@code{WHERE} Clauses/ &&
-      !$in_section_6_3){
-    $in_section_6_3= 1;
-    next;
+  my($names,$prompt)= @_;
+  if (scalar(@{$names}))
+  {
+    print STDERR "\n-------------- $prompt : \n\n";
+    my $name;
+    foreach $name (@{$names})
+    {
+      print STDERR "$name\n";
+    }
+    print STDERR "\n";
   }
+}
 
-  if ($_=~/\@section/ && $in_section_6_3){
-    $in_section_6_3= 0;
-    next;
+sub print_verbose_errors
+{
+  my($name_of_log_file)= @_;
+
+  my @without_help;
+  my @description_with_at;
+  my @example_with_at;
+  my @without_description;
+  my @without_example;
+    
+  print STDERR "\n-------------- parameters of help completeness : \n\n";
+    
+  my $count_lex= 0;
+  if (!open (TLEX,"<$path_to_lex_file"))
+  {
+    print STDERR "Error opening lex file \"$path_to_lex_file\" $!\n";
   }
+  else
+  {	
+    for (<TLEX>)
+    {
+      my ($a,$lex,$b)=m|(.+?)\"(.+?)\"(.+?)$|;
+      next if ($lex eq "");
+      $count_lex++;
+      next if (exists($topics{$lex}) || exists($keywords{$lex}));
+      push(@without_help,$lex);
+    }
+    close(TLEX);
+    print STDERR "number of lexems in \"$path_to_lex_file\" - $count_lex\n";
+  }
+    
+  my $name;
+  my @topic_names= keys(%topics);
+  foreach $name (@topic_names)
+  {
+    my $topic= $topics{$name};
+    push(@description_with_at,$name) if ($topic->{description}=~/\@/);
+    push(@example_with_at,$name) if ($topic->{example}=~/\@/);
+    push(@without_description,$name) if (!exists($topic->{description}));
+    push(@without_example,$name) if (!exists($topic->{example}));
+  }
+    
+  my $count_categories= scalar(keys(%categories));
+  print STDERR "number of help categories          - ",$count_categories,"\n";
+  my $count_topics= scalar(@topic_names);
+  print STDERR "number of help topics              - ",$count_topics,"\n";
+  my $count_keywords= scalar(keys(%keywords));
+  print STDERR "number of help keywords            - ",$count_keywords,"\n";
+    
+  my $count_without_help= scalar(@without_help);
+  print_bad_names(\@without_help,"lexems without help (".
+                            $count_without_help." ~ ".
+                            (int (($count_without_help/$count_lex)*100)).
+                            "%)");
+  print_bad_names(\@description_with_at,
+          " topics below have symbol \'@\' in their descriptions.\n".
+          "it's probably the litter from 'texi' tags (script needs fixing)");
+  print_bad_names(\@example_with_at,
+          " topics below have symbol \'@\' in their examples.\n".
+          "it's probably the litter from 'texi' tags (script needs fixing)");
+  print_bad_names(\@without_description,"topics without description");
+    
+  my $count_without_example= scalar(@without_example);
+  print_bad_names(\@without_example,"topics without example (".
+                            $count_without_example." ~ ".
+                            (int (($count_without_example/$count_topics)*100)).
+                            "%)");
+}
 
-  if (!$in_section_6_3) { next; }
+print_verbose_errors if ($verbose_option ne 0);
 
-  my $c_name= "";
+# output result 
 
-  ($c_name)=m|\@c for_mysql_help,(.+?)$|;
-  if (!($c_name eq "") && ! ($c_name =~ m/$cat_name/i)){
-    ($cat_name)= $c_name;
-    new_category($cat_name);
-    next;
+sub print_insert_header
+{
+  my($count,$header)= @_;
+    
+  if ($count % $insert_portion_size ne 0) {
+    print ",";
+  } else {
+    print ";\n" if ($count ne 0);
+    print "$header";
   }
+}
 
-  ($c_name)=m|\@subsubsection (.+?)$|;
-  if (!($c_name eq "") && ! ($c_name =~ m/$cat_name/i)){
-    ($cat_name)= $c_name;
-    new_category($cat_name);
-    next;
-  }
+print "delete from help_topic;\n";
+print "delete from help_category;\n";
+print "delete from help_keyword;\n";
+print "delete from help_relation;\n\n";
 
-  ($c_name)=m|\@subsection (.+?)$|;
-  if (!($c_name eq "") && ! ($c_name =~ m/$cat_name/i)){
-    ($cat_name)= $c_name;
-    new_category($cat_name);
-    next;
+my @category_names= keys(%categories);
+if (scalar(@category_names))
+{
+  my $cat_name;
+  my $count= 0;
+  foreach $cat_name (@category_names)
+  {
+    $categories{$cat_name}->{__id__}= $count;
+    $count++;
   }
 
-  ($f_name)=m|\@findex (.+?)$|;
-  if (!($f_name eq "")){
-    flush_all($mode);
-    ($func_name)= ($f_name);
-    $mode= "text";
-    next;
+  my $header= "insert into help_category ".
+            "(help_category_id,name,parent_category_id) values ";
+  $count= 0;
+  foreach $cat_name (@category_names)
+  {
+    print_insert_header($count,$header);
+    my $parent_cat_name= $categories{$cat_name}->{__parent_category__};
+    my $parent_cat_id= $parent_cat_name eq "" 
+        ? "-1" : $categories{$parent_cat_name}->{__id__};
+    print "($count,\"$cat_name\",$parent_cat_id)";
+    $count++;
   }
+  printf ";\n\n";
+}
 
-  if ($_=~/\@example/ && ($mode eq "text")){
-    $mode= "example";
-    next;
+my @topic_names= keys(%topics);
+if (scalar(@topic_names))
+{
+  my $header= "insert into help_topic ".
+      "(help_topic_id,help_category_id,name,description,example) values ";
+  my $topic_name;
+  my $count= 0;
+  foreach $topic_name (@topic_names)
+  {
+    print_insert_header($count,$header);
+    my $topic= $topics{$topic_name};
+    print "($count,";
+    print "$topic->{category}->{__id__},";
+    print "\"$topic_name\",";
+    print "\"$topic->{description}\",";
+    print "\"$topic->{example}\")";
+    $topics{$topic_name}->{__id__}= $count;
+    $count++;
   }
+  printf ";\n\n";
+}
 
-  if ($_=~/\@end example/ && ($mode eq "example")){
-    flush_all($mode);
-    next;
+my @keywords_names= keys(%keywords);
+if (scalar(@keywords_names))
+{
+  my $header= "insert into help_keyword (help_keyword_id,name) values ";
+  my $keyword_name;
+  my $count= 0;
+  foreach $keyword_name (@keywords_names)
+  {
+    print_insert_header($count,$header);
+    print "($count,\"$keyword_name\")";
+    $count++;
   }
-
-  if ($mode eq "text")    { $text    .= $_; }
-  if ($mode eq "example") { $example .= $_; }
+  printf ";\n\n";
+    
+  $header= "insert into help_relation ".
+	"(help_topic_id,help_keyword_id) values ";
+  $count= 0;
+  my $count_keyword= 0;
+  foreach $keyword_name (@keywords_names)
+  {
+    my $topic_name;
+    foreach $topic_name (keys(%{$keywords{$keyword_name}}))
+    {
+      print_insert_header($count,$header);
+      print "($topics{$topic_name}->{__id__},$count_keyword)";
+      $count++;
+    }
+    $count_keyword++;
+  }
+  printf ";\n\n";
 }
-
-
-print "DELETE help_category ";
-print "FROM help_category ";
-print "LEFT JOIN help_relation ON help_category.help_category_id=help_relation.help_category_id ";
-print "WHERE help_relation.help_category_id is null;"