Docs/header_specs.pl

   1 #!/usr/bin/perl -w
   2
   3 use strict;
   4 use warnings;
   5 use IO::File;
   6
   7
   8 #------------------------------------------
   9 #
  10 my @header_specs = (
  11     { language => [ 'C' ],
  12       begin => '/****',
  13       mid   => '*',
  14       end_1 => '****',
  15       end_2 => '/****',
  16       rem_begin => '/*',
  17       rem_end   => '*/'
  18     },
  19
  20     { language => [ 'Modula-2' ],
  21       begin => '(****',
  22       mid   => '*',
  23       end_1 => '****',
  24       end_2 => '(****',
  25       rem_begin => '(*',
  26       rem_end   => '*)'
  27     },
  28
  29     { language => [ 'Pascal' ],
  30       begin => '{****',
  31       mid   => '*',
  32       end_1 => '****',
  33       end_2 => '{****',
  34       rem_begin => '{*',
  35       rem_end   => '*}'
  36     },
  37
  38     { language => [ 'C++' ],
  39       begin => '//****',
  40       mid   => '//',
  41       end_2 => '//****',
  42     },
  43
  44     { language => [ 'Tcl', 'Perl' ],
  45       begin => '#****',
  46       mid   => '#',
  47       end_2 => '#****',
  48     },
  49
  50     { language => [ 'LaTeX/TeX', 'Postscript' ],
  51       begin => '%****',
  52       mid   => '%',
  53       end_2 => '%****',
  54     },
  55
  56     { language => [ 'Occam' ],
  57       begin => '__****',
  58       mid   => '__',
  59       end_2 => '__****',
  60     },
  61
  62
  63 );
  64
  65 #--------------------------------------------------------------------
  66 #
  67
  68
  69 sub make_robodoc_rc_file {
  70     my $spec = shift;
  71     my $rc_file = "";
  72
  73     $rc_file .= "header markers:\n";
  74     $rc_file .= "  $spec->{begin}\n";
  75     $rc_file .= "remark markers:\n";
  76     $rc_file .= "  $spec->{mid}\n";
  77     $rc_file .= "end markers:\n";
  78     if ( exists( $spec->{end_1} ) ) {
  79         $rc_file .= "  $spec->{end_1}\n";
  80     }
  81     if ( exists( $spec->{end_2} ) ) {
  82         $rc_file .= "  $spec->{end_2}\n";
  83     }
  84
  85     if ( exists( $spec->{rem_end} ) ) {
  86         $rc_file .= "remark begin markers:\n";
  87         $rc_file .= "  $spec->{rem_begin}\n";
  88         $rc_file .= "remark end markers:\n";
  89         $rc_file .= "  $spec->{rem_end}\n";
  90     }
  91
  92     return $rc_file;
  93 }
  94
  95
  96 #
  97 # given a header spec this returns an example header
  98 # that does not contain any source items.
  99 #
 100 sub make_example_header_simple {
 101     my $spec = shift;
 102     my $header = "";
 103
 104     $header = $spec->{begin} . "f* ModuleName/Foo\n";
 105     $header .= $spec->{mid} . " FUNCTION\n";
 106     $header .= $spec->{mid} . "   Foo computes the foo factor\n";
 107     $header .= $spec->{mid} . "   using a fudge factor.\n";
 108     if ( exists( $spec->{end_1} ) ) {
 109         $header .= $spec->{end_1} . "\n";
 110         $header .= $spec->{rem_end} . "\n";
 111     } else {
 112         $header .= $spec->{end_2} . "\n";
 113     }
 114 }
 115
 116
 117 sub make_example_header {
 118     my $spec = shift;
 119     my $header = "";
 120
 121     $header = $spec->{begin} . "f* ModuleName/Foo\n";
 122     $header .= $spec->{mid} . " FUNCTION\n";
 123     $header .= $spec->{mid} . "   Foo computes the foo factor\n";
 124     $header .= $spec->{mid} . "   using a fudge factor.\n";
 125     $header .= $spec->{mid} . " SYNOPSIS\n";
 126     if ( exists( $spec->{rem_end} ) ) {
 127         $header .= $spec->{rem_end} . "\n";
 128     } else {
 129
 130     }
 131     $header .= "int Foo( int fudge )\n";
 132     if ( exists( $spec->{rem_begin} ) ) {
 133         $header .= $spec->{rem_begin} . "\n";
 134     } else {
 135
 136     }
 137     $header .= $spec->{mid} . " INPUTS\n";
 138     $header .= $spec->{mid} . "   fudge -- the fudge factor\n";
 139     $header .= $spec->{mid} . " SOURCE\n";
 140     if ( exists( $spec->{rem_end} ) ) {
 141         $header .= $spec->{rem_end} . "\n";
 142     } else {
 143
 144     }
 145
 146     $header .= "\n more source code..\n\n";
 147
 148     if ( exists( $spec->{rem_end} ) ) {
 149         $header .= $spec->{end_2};
 150         $header .= $spec->{rem_end} . "\n";
 151     } else {
 152         $header .= $spec->{end_2} . "\n";
 153     }
 154
 155     return $header;
 156 }
 157
 158
 159
 160
 161 sub make_examples_for_manual {
 162     my $filename = "header_examples.xml";
 163     my $file = IO::File->new(">$filename") or die "$filename : $!";
 164     foreach my $spec ( @header_specs ) {
 165         foreach my $language ( @{$spec->{language}} ) {
 166             print $file "<section>\n";
 167             print $file "<title>$language</title>\n";
 168             print $file "\n\n";
 169
 170             print $file "<example>\n";
 171             print $file "<title>A simple header without any source items in $language.</title>\n";
 172             print $file "<programlisting>\n";
 173             print $file make_example_header_simple( $spec );
 174             print $file "</programlisting>\n";
 175             print $file "</example>\n";
 176             print $file "\n\n";
 177
 178             print $file "<example>\n";
 179             print $file "<title>A header with source items in $language.</title>\n";
 180             print $file "<programlisting>\n";
 181             print $file make_example_header( $spec );
 182             print $file "</programlisting>\n";
 183             print $file "</example>\n";
 184             print $file "\n\n";
 185
 186             print $file "<example>\n";
 187             print $file "<title>The robodoc.rc file required for $language if it were not supported by default.</title>\n";
 188             print $file "<programlisting>\n";
 189             print $file make_robodoc_rc_file( $spec );
 190             print $file "</programlisting>\n";
 191             print $file "</example>\n";
 192
 193             print $file "</section>\n";
 194         }
 195     }
 196
 197     $file->close();
 198 }
 199
 200
 201
 202 make_examples_for_manual;
 203