[Rd] Sd2Rd command (PR#7791)

[lunde.eric at mayo.edu]

Full_Name: Eric Lunde
Version: 2.0.1
OS: Solaris 9
Submission from: (NULL) (129.176.151.21)


Hi R Devel,

I am assisting one of my fellow R users who is developing a package for both
Splus and R.  He has been using the Sd2Rd command to convert his sgml help files
into Rd help files.  We believe we have found a bug.  We noticed that if an sgml
help file has multiple <s-topic> tags, each of those tags gets translated into
both a \name{} and an \alias{} tag in the Rd file.  The desired functionality is
a \name{} tag is written once (given the value of the first <s-topic>) and an
\alias tag is written for each <s-topic> tag.  Having multiple \name{} tags
caused R CMD check to holler the following:

* checking Rd files ... WARNING
Rd files with duplicate 'name':
 /people/biostat3/sinnwell/Rdir/Make/haplo.stats/man/haplo.score.Rd
These entries must be unique in an Rd file.

I believe that the developers of Sd2Rd attempted to prevent this from happening.
 They use a variable named nalias (used as a Boolean and initialized to 0).  If
nalias is equal to 0 then the \name{} tag is written to the output Rd file and
nalias is given the value 1.  This nalias is not used anywhere else in the
subroutine which makes me think that the developers were trying to use nalias as
a static variable and hoped it would retain the value of 1 for the next time the
subroutine process_sub_group is called.  Here is the code:

sub process_sub_group{
  my $topic = $_[0];
  my $text = $_[1];
  my $nalias = 0;
  my $example = 0;

  . . .
    if(!$nalias) {
      print "\\name{$text}\n";
      $nalias = 1;
      $fun = $text;
    }
    print "\\alias{$text}\n";
  . . .
}

I propose that the code be altered slightly to gain the proper functionality. 
If process_sub_group was wrapped in braces and nalias was removed from inside
process_sub_group and was declared outside the subroutine but inside the braces,
nalias would retain its value from call to call and the "static" mentality of
nalias would be gained.  My proposed code:

{
my $nalias = 0;

sub process_sub_group{
  my $topic = $_[0];
  my $text = $_[1];
  #my $nalias = 0;
  my $example = 0;

  . . . 
    if(!$nalias) {
      print "\\name{$text}\n";
      $nalias = 1;
      $fun = $text;
    }
    print "\\alias{$text}\n"
  . . .
}
}

Other functions will be able to call process_sub_group just as before, but
nalias will retain its value of 1 during the second, third, etc calls to
process_sub_group.  Thanks for your consideration,

Eric Lunde
Analyst/Programmer
Mayo Clinic
Phone: 507-284-5630
Email: lunde.eric at mayo.edu