8.8. mkcdoc.pl

[<<<] [>>>]

Extract the BASIC command reference documentation from the C source files that are in the C source file in the directory `commands'

The souce code of the file `mkcdoc.pl' is:

my %SECTION;
my %COMMAND;
my %TITLE; # the title line of the command
my %SUBTITLE; # the subtitle of the command
my %DISPLAY; # the display of the command in the TOC
my @files;
my @$SourceFile;
for @$SourceFile ( @files ){
  &ProcessFile( @$SourceFile );
  }
&CreateOutput;
&CreateTexiOutput;
exit;
  return unless open(F,"commands/@$file");
  while( defined(@$line = <F>) ){
    if( @$line =~ /^\/\*\*(.*)\s*@$/ ){
      if( defined(@$ActualCommand) ){
        warn "The command @$ActualCommand was not closed. Closing implicitly.";
        @$ActualCommand = undef;
        }
      @$ActualCommand = @$1;
      next;
      }
    if( @$line =~ /^\*\// ){
      @$ActualCommand = undef;
      next;
      }
    if( @$line =~ /^=section\s+(.*)/ ){
      my @sections = split /\s+/ , @$1;
      for @$section ( @sections ){
        push @{@$SECTION{@$section}},@$ActualCommand;
        }
      next;
      }
    if( @$line =~ /^=title\s+(.*)/ ){
      if( defined(@$TITLE{@$ActualCommand}) ){
        my @$err;
        @$err = "Title is double defined for @$ActualCommand\n" .
               "   " . @$TITLE{@$ActualCommand} . "\n" .
               "   " . @$1 . "\n" ;
        warn @$err;
        }
      @$TITLE{@$ActualCommand} = @$1;
      next;
      }
    if( @$line =~ /^=subtitle\s+(.*)/ ){
      if( defined(@$SUBTITLE{@$ActualCommand}) ){
        warn "Subtitle is double defined for @$ActualCommand";
        }
      @$SUBTITLE{@$ActualCommand} = @$1;
      next;
      }
    if( @$line =~ /^=display\s+(.*)/ ){
      if( defined(@$DISPLAY{@$ActualCommand}) ){
        warn "Title is double defined for @$ActualCommand";
        }
      @$DISPLAY{@$ActualCommand} = @$1;
      next;
      }
sub CreateOutput {
  my @$command;
  my @$lines;
  my @commands;
  my @$section;
  my @sections;
  mkdir "../html";
  open(F,">../html/commands.html") or die "Can not open output file.";
  print F <<END;
<HTML>
<HEAD>
<TITLE></TITLE>
</HEAD>
<BODY>
<H1>ScriptBasic commands and functions reference</H1>
  for @$section ( @sections ){
    print F "<a href=\"#section_@$section\">@$section</A>\n";
    }
  for @$command ( @commands ){
    my @$display;
    @$display = @$command;
    @$display = @$DISPLAY{@$command} if defined @$DISPLAY{@$command};
    print F "<a href=\"#command_@$command\">@$display</A>\n";
    }
  for @$section ( @sections ){
    print F "<H3><a name=\"section_@$section\">@$section</A></H3>\n";
	print F "<FONT SIZE=\"1\">\n";
    my @scommands = sort @{@$SECTION{@$section}};
    my @$scommand;
    for @$scommand (@scommands){
      my @$display;
      @$display = @$scommand;
      @$display = @$DISPLAY{@$scommand} if defined @$DISPLAY{@$scommand};
      print F "<a href=\"#command_@$scommand\">@$display</A>\n";
      }
    print F "</FONT\>\n";
    }
  for @$command ( @commands ){
    my @$title = @$command;
    my @$line;
    my @$verbatim = 0;
    my @$subtitle;
    my @$FH;
    #
    # print lines that start a command
    #
      if( @$line =~ /^\s*=itemize\s*@$/ ){
  	if( @$FH ){
          print DF "<UL>\n";
  	  }else{
          print F "<UL>\n";
  	  }
        next;
        }
      if( @$line =~ /^\s*=noitemize\s*@$/ ){
  	if( @$FH ){
          print DF "</UL>\n";
  	  }else{
          print F "</UL>\n";
  	  }
        next;
        }
      my @$l_line = @$line;
      while( @$l_line =~ /R\<(\w+?)\>/ ){
        my @$d = @$1;
        @$d = @$DISPLAY{@$d} if defined @$DISPLAY{@$d};
        @$l_line =~ s/R\<(\w+?)\>/\001a href=\"#command_@$1\">@$d\001\/a>/;
        }
      @$l_line =~ s/T\<(.+?)\>/\001tt>@$1\001\/tt>/g;
      @$l_line =~ s/B\<(.+?)\>/\001B>@$1\001\/B>/g;
      @$l_line =~ s/I\<(.+?)\>/\001I>@$1\001\/I>/g;
      @$l_line =~ tr{\001}{<};
      if( @$FH ){
        print DF @$l_line;
      }else{
        print F @$l_line;
        }
      }
    #
    # print lines that close a command
    #
    print F "</BLOCKQUOTE>\n";
    if( @$FH ){
	  print DF <<END;
<P><a href="../commands.html#command_@$command">BACK</a>
</BODY>
</HTML>
END
	  close DF; # if it was opened
	  }
    }
#################################################
  @commands = sort keys %COMMAND;
  @sections = sort keys %SECTION;
  print F "\@chapter Command reference\n";
    @$title = @$TITLE{@$command} if defined @$TITLE{@$command};
    @$subtitle = undef;
    @$subtitle = @$SUBTITLE{@$command} if defined @$SUBTITLE{@$command};
    print F "\n\@section @$title\n\n";
    print F "\@b{@$subtitle}\n" if defined @$subtitle;
    for @$line ( @{@$COMMAND{@$command}} ){
      if( @$line =~ /^\s*=details\s*@$/ ){
        print F "\@subsection @$command Details\n";
        next;
        }
      if( @$line =~ /^\s*=verbatim\s*@$/ ){
        @$verbatim++;
        print F "\@example\n";
        next;
        }
      if( @$line =~ /^\s*=noverbatim\s*@$/ ){
        @$verbatim--;
        print F "\@end example\n";
        next;
        }
      if( @$verbatim ){
        print F @$line;
        next;
        }
      if( @$line =~ /^\s*@$/ ){
        print F "\n\n";
        next;
        }
      @$l_line =~ s/\@/\@\@/g;
      @$l_line =~ s/\@$/\@\@$/g;
      @$l_line =~ s/\{/\@\{/g;
      @$l_line =~ s/\}/\@\}/g;
      @$l_line =~ s[<a href=".*?">(.*?)</a>][\@xref{@$1}]gi;
      @$l_line =~ s/R\<(.+?)\>/\@xref\{@$1\}/g;
      @$l_line =~ s/T\<(.+?)\>/\@code\{@$1\}/g;
      @$l_line =~ s/B\<(.+?)\>/\@b\{@$1\}>/g;
      @$l_line =~ s/I\<(.+?)\>/\@emph\{@$1\}>/g;
      print F @$l_line;
      }
    }


[<<<] [>>>]