# HG changeset patch
# User Rik <rik@octave.org>
# Date 1640796093 28800
# Node ID 0ef88c48578674c3f19d4b352c578379b3dff759
# Parent  83f9f8bda88362cf47a4cc10f126543d362e2e32
doc: Allow links to old-style class files (@class/) in Texinfo @seealso macro.

* mk-doc-cache.pl: Replace '@' with '@@' when expanding @seealso macro to
@xseealso macro.  Also, many code formatting tweaks for clarity.

* __makeinfo__.m: Replace '@' with '@@' when expanding @seealso macro to
@xseealso macro.

diff -r 83f9f8bda883 -r 0ef88c485786 doc/interpreter/mk-doc-cache.pl
--- a/doc/interpreter/mk-doc-cache.pl	Tue Dec 28 18:59:33 2021 -0500
+++ b/doc/interpreter/mk-doc-cache.pl	Wed Dec 29 08:41:33 2021 -0800
@@ -34,25 +34,22 @@
 use File::Temp;
 
 my $doc_delim = "\x{1d}";
-my $tex_delim_pat = qr/\Q-*- texinfo -*-\E/;
+my $tex_delim_ptn = qr/\Q-*- texinfo -*-\E/;
 
-## Returns a File::Temp object with texinfo code.
+## Returns a File::Temp object with Texinfo code.
 sub make_texinfo_file
 {
   my $srcdir = shift;
   my $macro_fpath = shift;
   my @docstrings = @_;
 
-  my $t_file = File::Temp->new (UNLINK => 1);
+  my $tmpfile = File::Temp->new (UNLINK => 1);
 
   ## Only the first file is the macro file.  Copy its contents verbatim.
-  open (my $macro_fh, "<", $macro_fpath)
+  open (my $FH_macro, "<", $macro_fpath)
     or die "Unable to open $macro_fpath for reading: $!\n";
-  while (<$macro_fh>)
-    {
-      print {$t_file} $_;
-    }
-  close ($macro_fh);
+  while (<$FH_macro>) {  print {$tmpfile} $_;  }
+  close ($FH_macro);
 
   foreach my $filepath (@docstrings)
     {
@@ -64,35 +61,44 @@
           ## tree, from released sources.
           $filepath = File::Spec->catfile ($srcdir, $filepath);
         }
-      open (my $fh, "<", $filepath)
+      open (my $FH, "<", $filepath)
         or die "Unable to open $filepath for reading: $!\n";
 
       my $in_header = 1;
-      while (my $line = <$fh>)
+      while (my $line = <$FH>)
         {
           ## DOCSTRINGS header ends once we find the first function.
           if ($in_header && $line =~ m/^$doc_delim/)
             {
               $in_header = 0;
             }
-          next if $in_header;
-          next if $line =~ /$tex_delim_pat/;
+          next if ($in_header);
+          next if ($line =~ /$tex_delim_ptn/);
 
-          $line =~ s/\@seealso/\@xseealso/g;
+          ## Change @seealso to private @xseealso macro
+          if ($line =~ m'@seealso')
+          {
+            ## Combine @seealso macro spread over multiple lines
+            while ($line !~ m/}$/) {  $line .= <$FH>;  }
 
-          ## escape {}@ characters for texinfo
-          $line =~ s/([{}\@])/\@$1/g
-            if $line =~ m/^$doc_delim/;
+            ## escape @ characters in old-style class names like @ftp
+            $line =~ s/\@(\w)/\@\@$1/g;
+            $line =~ s'@@seealso'@xseealso';
+          }
 
-          print {$t_file} $line;
+          ## escape {}@ characters in Texinfo anchor name (e.g., @ftp/dir.m)
+          $line =~ s/([{}@])/\@$1/g if ($line =~ m/^$doc_delim/);
+
+          print {$tmpfile} $line;
         }
-      close ($fh);
+      close ($FH);
     }
 
-  print {$t_file} $doc_delim;
+  print {$tmpfile} $doc_delim;
 
-  $t_file->flush ();
-  return $t_file;
+  $tmpfile->flush ();
+
+  return $tmpfile;
 }
 
 sub get_info_text
@@ -106,7 +112,7 @@
     if (! defined $info_text);
 
   die "makeinfo produced no output!"
-    if ! $info_text;
+    if (! $info_text);
 
   return $info_text;
 }
@@ -117,7 +123,7 @@
 
   ## Constant patterns.  We only check for two underscores at the end,
   ## and not at the start, to also skip @class/__method__
-  my $private_name_pat = qr/__$/;
+  my $private_name_ptn = qr/__$/;
 
   my @formatted = ();
 
@@ -135,7 +141,7 @@
 
       my ($symbol, $doc) = split (/[\r\n]/, $block, 2);
 
-      next if (length ($symbol) > 2 && $symbol =~ m/$private_name_pat/);
+      next if (length ($symbol) > 2 && $symbol =~ m/$private_name_ptn/);
 
       if (! defined ($doc))
       {
@@ -156,6 +162,7 @@
 
       push (@formatted, [($symbol, $doc, $first_sentence)]);
     }
+
   return @formatted;
 }
 
@@ -164,22 +171,26 @@
   my ($str) = @_;
   my $len = length ($str);
 
-  print "# name: <cell-element>\n";
-  print "# type: sq_string\n";
-  print "# elements: 1\n";
-  print "# length: $len\n";
-  print "$str\n\n\n";
+  print <<__END_OF_ELEMENT__;
+# name: <cell-element>
+# type: sq_string
+# elements: 1
+# length: $len
+$str\n\n
+__END_OF_ELEMENT__
 }
 
 sub print_cache
 {
   my $num = @_;
 
-  print "# created by mk-doc-cache.pl\n";
-  print "# name: cache\n";
-  print "# type: cell\n";
-  print "# rows: 3\n";
-  print "# columns: $num\n";
+  print <<__END_OF_CACHE_HDR__;
+# created by mk-doc-cache.pl
+# name: cache
+# type: cell
+# rows: 3
+# columns: $num
+__END_OF_CACHE_HDR__
 
   foreach my $elt (@_)
     {
@@ -194,6 +205,8 @@
     }
 }
 
+## FIXME: This is a very C/C++ way of coding things.
+## Perl convention would just be to have the executable code at end of file.
 sub main
 {
   my $srcdir = shift;
diff -r 83f9f8bda883 -r 0ef88c485786 scripts/help/__makeinfo__.m
--- a/scripts/help/__makeinfo__.m	Tue Dec 28 18:59:33 2021 -0500
+++ b/scripts/help/__makeinfo__.m	Wed Dec 29 08:41:33 2021 -0800
@@ -101,7 +101,12 @@
   endif
   ## Texinfo crashes if @end tex does not appear first on the line.
   text = regexprep (text, '^ +@end tex', '@end tex', 'lineanchors');
-  text = regexprep (text, '@seealso', '@xseealso');
+  ## Replace @seealso with Octave specific @xseealso macro, and escape '@'
+  [s, e] = regexp (text, '@seealso{.*}');
+  if (! isempty (s))
+    esc_text = strrep (text(s+8:e), '@', '@@');
+    text = [text(1:s), 'xseealso', esc_text, text(e+1:end)];
+  endif
 
   ## We don't want *ref macros to clutter plain text output with "Note ..."
   if (strcmp (output_type, "plain text"))