Doxygen/vxl_doxy.pl

   1 #!/bin/sh
   2 # -*- perl -*-
   3 exec perl -w -x $0 ${1+"$@"}
   4 #!perl
   5 #line 6
   6 # If Windows barfs at line 3 here, you will need to run perl -x vxl_doxy.pl
   7 # You can set up as a permanent file association using the following commands
   8 #  >assoc .pl-PerlScript
   9 #  >ftype PerlScript=Perl=C:\Perl\bin\Perl.exe -x "%1" %*
  10
  11 # Script to change the perceps documentation format to Doxygen (JavaDoc) format
  12 # Authors:
  13 #         Dave Cooper
  14 #         Maarten Vergauwen
  15 # Date:
  16 #      17/02/2000
  17 # Modified:
  18 # 11 April 2001 Ian Scott.   Remove support for old perceps commands
  19 #  5 May   2001 Geoff Cross. Correctly handle end of verbatim blocks. Allow two contiguous comments
  20 #  10 May  2001 Ian Scott. Merged Geoffs and my changes
  21
  22
  23 # patterns to be matched
  24 $verbpatt = '\\\\verbatim';
  25 $endverbpatt = '\\\\endverbatim';
  26 $slashslashpatt = '^\\s*//';
  27 $slashslashcolonpatt = '^\\s*//:';
  28 $slashstarstarpatt = '/**';
  29 $spacespacepatt = '  ';
  30 $starpatt = '*';
  31 $starslashpatt = '*/';
  32
  33 # variables that keep state:
  34
  35 # comment found -> first line should start with /**, next lines with *, last line with */
  36 $comment = 0;
  37
  38 # verbatim found -> lines should not start with * (visible in Doxygen)
  39 $verbatim = 0;
  40 # finish verbatim mode at the end of this line.
  41 $should_end_verbatim = 0;
  42
  43 $debug = 0;
  44
  45 # mainloop
  46 while (<>)
  47 {
  48     # preprocessing
  49     s/\bVCL_SUNPRO_CLASS_SCOPE_HACK\s*\([^()]*\)//g;
  50     s/\bVCL_SUNPRO_ALLOCATOR_HACK\s*\(([^()]*)\)/$1/g;
  51     s/\bVCL_CAN_STATIC_CONST_INIT_(INT|FLOAT)\b/1/g;
  52     s/\bVCL_STATIC_CONST_INIT_(INT|FLOAT)\s*\(([^()]*)\)/= $2/g;
  53     s/\bVCL_DFL_TYPE_PARAM_STLDECL\s*\(([^,()]*),([^,()]*)\)/class $1 = $2 /g;
  54     s/\bDECLARE_DYNCREATE\s*\([^()]*\)//g; # for MFC
  55
  56     if ( $should_end_verbatim )
  57     {
  58         $verbatim = 0;
  59         $should_end_verbatim = 0;
  60     }
  61
  62     # found verbatim ?
  63     if ( m/$verbpatt/ ) { $verbatim = 1; };
  64
  65     # found endverbatim ?
  66     if ( m/$endverbpatt/ ) { $should_end_verbatim = 1; };
  67
  68     # found start of comment: "//:"  ?
  69     if ( s!$slashslashcolonpatt!$slashstarstarpatt! )
  70     {
  71         chomp; s/\s*$//;
  72         # escape a space following a dot, add a dot at the end,
  73 #       # and finish brief doc, unless the line is empty or only has '\file':
  74         unless (m!^\s*\/\*\*\s*(\\file)?\s*$!) {
  75 #         s/\. /.\\ /g; s/(\.)?\s*$/. \*\/\n\/\*/;
  76           s/\. /.\\ /g; s/(\.)?\s*$/.\n/;
  77         }
  78         else { s/$/\n/; }
  79
  80         if ($comment)
  81         {
  82             # Previous comment hasn't ended--two contiguous comment blocks.
  83             # (Should not happen.)
  84             print STDERR "Two contiguous comment blocks -- this should not happen\n";
  85             print "*/\n";
  86         }
  87         $comment = 1;
  88         print; next;
  89     }
  90
  91     # Replace '$' with '\f$' (TeX math mode)
  92     s/(\\f)?\$(.+?)(\\f)?\$/\\f\$$2\\f\$/g if ($comment);
  93
  94     # found continuation of comment WITH verbatim -> no "*"
  95     if ( m!$slashslashpatt! && $verbatim && $comment)
  96     {
  97         s!$slashslashpatt!$spacespacepatt!;
  98 #       # Make 'Modifications' a section title:
  99 #       s!\b(Modifications?)\b\:?!\<H2\>$1\<\/H2\>!;
 100         # remove lines of the form ========= or +-+-+-+-+ or ********* or longer:
 101         print unless m/^\s*[*=+-]{9,}\s*$/; next;
 102     }
 103
 104     # found continuation of comment WITHOUT verbatim -> start line with "*"
 105     if ( m!$slashslashpatt! && $comment )
 106     {
 107         s!$slashslashpatt!$starpatt!;
 108         # remove lines of the form ========= or +-+-+-+-+ or ********* or longer:
 109         print unless m/^\s*[*=+-]{9,}\s*$/; next;
 110     }
 111
 112     # found end of comment -> start line with */
 113     # NOTE that *every* line within a comment (also empty lines) *must* start with // !
 114     # (In an earlier version of this script, empty lines were allowed inside comments.)
 115     if ( $comment && ! m!$slashslashpatt!  )
 116     {
 117         print "$starslashpatt\n";
 118         $comment = 0;
 119         print; next;
 120     }
 121
 122     # just print line if not in comment or in file
 123     if ( !$comment ) { print; next; }
 124
 125     # debug - print unprocessed lines (s.b. none)
 126     if ($debug) { print "LNP:\t"; print; }
 127 }