/[MITgcm]/MITgcm/doc/api_reference/protex
ViewVC logotype

Contents of /MITgcm/doc/api_reference/protex

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.2 - (show annotations) (download)
Fri Mar 26 23:46:11 2004 UTC (19 years, 8 months ago) by edhill
Branch: MAIN
Changes since 1.1: +3 -1 lines
 o most of a framework for building the API Reference automatically

1 #! /usr/bin/env perl
2 #
3 # $Id: protex,v 1.1 2004/03/26 19:41:44 edhill Exp $
4 #
5 #BOP
6 #
7 # !ROUTINE: ProTeX v. 2.00 - Translates DAO Prologues to LaTeX
8 #
9 # !INTERFACE:
10 # protex [-hbACFS7] ] [+-nlsxf] [src_file(s)]
11 #
12 # !DESCRIPTION:
13 # Perl filter to produce a \LaTeX compatible document
14 # from a DAO Fortran source code with standard Pro\TeX
15 # prologues. If source files are not specified it
16 # reads from stdin; output is always to stdout.
17 #
18 # \noindent
19 # {\bf Command Line Switches:} \vspace{0.2cm}
20 #
21 # \begin{center}
22 # \begin{tabular}{|c|l|} \hline \hline
23 # -h & Help mode: list command line options \\ \hline
24 # -b & Bare mode, meaning no preamble, etc. \\ \hline
25 # -i & internal mode: omit prologues marked !BOPI \\ \hline
26 # +/-n & New Page for each subsection (wastes paper) \\ \hline
27 # +/-l & Listing mode, default is prologues only \\ \hline
28 # +/-s & Shut-up mode, i.e., ignore any code from BOC to EOC \\ \hline
29 # +/-x & No LaTeX mode, i.e., put !DESCRIPTION: in verbatim mode \\ \hline
30 # +/-f & No source file info \\ \hline
31 # -A & Ada code \\ \hline
32 # -C & C++ code \\ \hline
33 # -F & F90 code (default) \\ \hline
34 # -7 & F77 code \\ \hline
35 # -S & Shell script \\ \hline \hline
36 # \end{tabular}
37 # \end{center}
38 #
39 # The options can appear in any order. The options, -h and -b, affect
40 # the input from all files listed on command-line input. Each of the
41 # remaining options effects only the input from the files listed after
42 # the option and prior to any overriding option. The plus sign
43 # turns off the option. For example, the command-line input,
44 # \bv
45 # protex -bnS File1 -F File2.f +n File3.f
46 # \ev
47 # will cause the option, {\tt -n} to affect the input from the files,
48 # {\tt File} and {\tt File2.f}, but not from {\tt File3.f}. The
49 # {\tt -S} option is implemented for {\tt File1} but is overridden by
50 # the {\tt -F} for files {\tt File2.f} and {\tt File3.f}.
51 #
52 #
53 # !SEE ALSO:
54 # For a more detailed description of ProTeX functionality,
55 # DAO Prologue and other conventions, consult:
56 #
57 # Sawyer, W., and A. da Silva, 1997: ProTeX: A Sample
58 # Fortran 90 Source Code Documentation System.
59 # DAO Office Note 97-11
60 #
61 #
62 # !REVISION HISTORY:
63 #
64 # 20Dec1995 da Silva First experimental version
65 # 10Nov1996 da Silva First internal release (v1.01)
66 # 28Jun1997 da Silva Modified so that !DESCRIPTION can appear after
67 # !INTERFACE, and !INPUT PARAMETERS etc. changed to italics.
68 # 02Jul1997 Sawyer Added shut-up mode
69 # 20Oct1997 Sawyer Added support for shell scripts
70 # 11Mar1998 Sawyer Added: file name, date in header, C, script support
71 # 05Aug1998 Sawyer Fixed LPChang-bug-support-for-files-with-underscores
72 # 10Oct1998 da Silva Introduced -f option for removing source file info
73 # from subsection, etc. Added help (WS).
74 # 06Dec1999 C. Redder Added LaTeX command "\label{sec:prologues}" just
75 # after the beginning of the proglogue section.
76 # 13Dec1999 C. Redder Increased flexbility in command-line
77 # interface. The options can appear in any
78 # order which will allow the user to implement
79 # options for select files.
80 # 01Feb1999 C. Redder Added \usepackage commands to preamble of latex
81 # document to include the packages amsmath, epsfig
82 # and hangcaption.
83 # 10May2000 C. Redder Revised LaTeX command "\label{sec:prologues}"
84 # to "\label{app:ProLogues}"
85 # 10/10/2002 da Silva Introduced ARGUMENTS keyword, touch ups.
86 #
87 # 15Jan2003 R. Staufer Modified table of contents to print only section headers - no descriptions
88 #
89 # 25Feb2003 R. Staufer Added BOPI/EOPI and -i (internal) switch to provide the option of omitting prologue information from output files.
90 #
91 #EOP
92 #----------------------------------------------------------------------------
93
94 # Keep this if you don't know what it does...
95 # -------------------------------------------
96 $[ = 1; # set array base to 1
97 $, = ' '; # set output field separator
98 $\ = "\n"; # set output record separator
99
100 # Set valid options lists
101 # -----------------------
102 $GlobOptions = 'hb'; # Global options (i.e for all files)
103 $LangOptions = 'ACFS7'; # Options for setting programming languages
104 $SwOptions = 'flinsx'; # Options that can change for each input
105 # file
106 $RegOptions = "$GlobOptions$LangOptions";
107 # Scan for global options until first first
108 # file is processed.
109
110 # Scan for global options
111 # -----------------------
112 $NFiles = 0;
113 Arg:
114 foreach $arg (@ARGV) {
115 $option = &CheckOpts ( $arg, $RegOptions, $SwOptions ) + 1;
116 if ( $option ) {
117 $rc = &GetOpts ( $arg, $GlobOptions );
118 next Arg; }
119
120 else { $NFiles++;
121 }# end if
122 }# end foreach
123
124 # If all input arguments are options, then assume the
125 # filename, "-", for the standard input
126 # --------------------------------------------------
127 if ( $NFiles == 0 ) { push (@ARGV, "-"); }
128
129 # Implement help option
130 # ---------------------
131 if ( $opt_h ) {
132 &print_help();
133 exit();
134 }#end if
135
136 # Optional Prologue Keywords
137 # --------------------------
138 @keys = ( "!INTERFACE:",
139 "!USES:",
140 "!PUBLIC TYPES:",
141 "!PRIVATE TYPES:",
142 "!PUBLIC MEMBER FUNCTIONS:",
143 "!PRIVATE MEMBER FUNCTIONS:",
144 "!PUBLIC DATA MEMBERS:",
145 "!PARAMETERS:",
146 "!ARGUMENTS:",
147 "!DEFINED PARAMETERS:",
148 "!INPUT PARAMETERS:",
149 "!INPUT/OUTPUT PARAMETERS:",
150 "!OUTPUT PARAMETERS:",
151 "!RETURN VALUE:",
152 "!REVISION HISTORY:",
153 "!BUGS:",
154 "!SEE ALSO:",
155 "!SYSTEM ROUTINES:",
156 "!FILES USED:",
157 "!REMARKS:",
158 "!TO DO:",
159 "!CALLING SEQUENCE:",
160 "!AUTHOR:",
161 "!CALLED FROM:",
162 "!LOCAL VARIABLES:" );
163
164 # Initialize these for clarity
165 # ----------------------------
166 $intro = 0; # doing introduction?
167 $prologue = 0; # doing prologue?
168 $first = 1; # first prologue?
169 $source = 0; # source code mode?
170 $verb = 0; # verbatim mode?
171 $tpage = 0; # title page?
172 $begdoc = 0; # has \begin{document} been written?
173
174 # Initial LaTeX stuff
175 # -------------------
176 &print_notice();
177 &print_preamble(); # \documentclass, text dimensions, etc.
178 &print_macros(); # short-hand LaTeX macros
179
180 # Main loop -- for each command-line argument
181 # -------------------------------------------
182 ARG:
183 foreach $arg (@ARGV) {
184
185 # Scan for non-global command-line options
186 # ----------------------------------------
187 $option = &CheckOpts ( $arg, $RegOptions, $SwOptions, "quiet" ) + 1;
188 if ( $option ) {
189 &GetOpts ( $arg, $SwOptions );
190 &SetOpt ( $arg, $LangOptions );
191 next ARG;
192
193 }# end if
194
195 # Determine the type of code, set corresponding search strings
196 # ------------------------------------------------------------
197 # if ( $opt_F ) { # FORTRAN
198 $comment_string = '!'; # -------
199 $boi_string = '!BOI';
200 $eoi_string = '!EOI';
201 $bop_string = '!BOP';
202 $eop_string = '!EOP';
203 $bopi_string = '!BOPI';
204 $eopi_string = '!EOPI';
205 $boc_string = '!BOC';
206 $eoc_string = '!EOC';
207 #}# end if
208
209 if ( $opt_7 ) { # f77
210 $comment_string = 'C'; # ---
211 $boi_string = 'CBOI';
212 $eoi_string = 'CEOI';
213 $bop_string = 'CBOP';
214 $eop_string = 'CEOP';
215 $bopi_string = 'CBOPI';
216 $eopi_string = 'CEOPI';
217 $boc_string = 'CBOC';
218 $eoc_string = 'CEOC';
219 }# end if
220
221 if ( $opt_A ) { # ADA
222 $comment_string = '--'; # ---
223 $boi_string = '--BOI';
224 $eoi_string = '--EOI';
225 $bop_string = '--BOP';
226 $eop_string = '--EOP';
227 $bopi_string = '--BOPI';
228 $eopi_string = '--EOPI';
229 $boc_string = '--BOC';
230 $eoc_string = '--EOC';
231 }# end if
232
233 if ( $opt_C ) {
234 $comment_string = '//'; # C
235 $boi_string = '//BOI'; # -
236 $eoi_string = '//EOI';
237 $bop_string = '//BOP';
238 $eop_string = '//EOP';
239 $bopi_string = '//BOPI';
240 $eopi_string = '//EOPI';
241 $boc_string = '//BOC';
242 $eoc_string = '//EOC';
243 }# end if
244
245 if ( $opt_S ) { # Script
246 $comment_string = '#'; # ------
247 $boi_string = '#BOI';
248 $eoi_string = '#EOI';
249 $bop_string = '#BOP';
250 $eop_string = '#EOP';
251 $bopi_string = '#BOPI';
252 $eopi_string = '#EOPI';
253 $boc_string = '#BOC';
254 $eoc_string = '#EOC';
255 }# end if
256
257 # Set file name parameters
258 # ------------------------
259 $InputFile = $arg;
260 @all_path_components = split( /\//, $InputFile );
261 $FileBaseName = pop ( @all_path_components );
262 $FileBaseName =~ s/_/\\_/g;
263 if ( $InputFile eq "-" ) {$FileBaseName = "Standard Input";}
264
265 # Set date
266 # --------
267 $Date = `date`;
268
269 # Open current file
270 # -----------------
271 open ( InputFile, "$InputFile" )
272 or print STDERR "Unable to open $InputFile: $!";
273
274 # Print page header
275 # -----------------
276 chomp($Date);
277 printf "\n\\markboth{Left}{Source File: %s, Date: %s}\n\n",
278 $FileBaseName, $Date;
279
280 LINE:
281 # Inner loop --- for processing each line of the input file
282 # ---------------------------------------------------------
283 while ( <InputFile> ) {
284 chop; # strip record separator
285
286 # !PARAMETERS: really mean !ARGUMENTS:
287 # ------------------------------------
288 # s/!PARAMETERS:/!ARGUMENTS:/g;
289
290 @Fld = split(' ', $_, 9999);
291
292 # Straight quote
293 # --------------
294 if ($Fld[1] eq '!QUOTE:') {
295 for ($i = 2; $i <= $#Fld; $i++) {
296 printf '%s ', $Fld[$i];
297 }# end for
298 print " ";
299 next LINE;
300 }# end if
301
302 # Handle optional Title Page and Introduction
303 # -------------------------------------------
304 if ($Fld[1] eq $boi_string) {
305 print ' ';
306 $intro = 1;
307 next LINE;
308 }# end if
309
310 if ($Fld[2] eq '!TITLE:') {
311 if ( $intro ) {
312 shift @Fld;
313 shift @Fld;
314 @title = @Fld;
315 $tpage = 1;
316 next LINE;
317 }# end if
318 }# end if
319
320 if ($Fld[2] eq '!AUTHORS:') {
321 if ( $intro ) {
322 shift @Fld;
323 shift @Fld;
324 @author = @Fld;
325 $tpage = 1;
326 next LINE;
327 }# end if
328 }# end if
329
330 if ($Fld[2] eq '!AFFILIATION:') {
331 if ( $intro ) {
332 shift @Fld;
333 shift @Fld;
334 @affiliation = @Fld;
335 $tpage = 1;
336 next LINE;
337 }# end if
338 }# end if
339
340 if ($Fld[2] eq '!DATE:') {
341 if ( $intro ) {
342 shift @Fld;
343 shift @Fld;
344 @date = @Fld;
345 $tpage = 1;
346 next LINE;
347 }# end if
348 }# end if
349
350 if ($Fld[2] eq '!INTRODUCTION:') {
351 if ( $intro ) {
352 &do_beg();
353 print ' ';
354 print '%..............................................';
355 shift @Fld;
356 shift @Fld;
357 print "\\section{@Fld}";
358 next LINE;
359 }# end if
360 }# end if
361
362
363 # End of introduction
364 # -------------------
365 if ($Fld[1] eq $eoi_string) {
366 print ' ';
367 print '%/////////////////////////////////////////////////////////////';
368 print "\\newpage";
369 $intro = 0;
370 next LINE;
371 }# end if
372
373 # Beginning of prologue
374 # ---------------------
375 if ($Fld[1] eq $bop_string) {
376 if ( $source ) { &do_eoc(); }
377 print ' ';
378 print '%/////////////////////////////////////////////////////////////';
379 &do_beg();
380 if ($first == 0) {
381 ### print "\\newpage";
382 print " ";
383 print "\\mbox{}\\hrulefill\\ ";
384 print " ";}
385 else {
386 unless($opt_b){print "\\section{Routine/Function Prologues} \\label{app:ProLogues}";}
387 }# end if
388
389 $first = 0;
390 $prologue = 1;
391 $verb = 0;
392 $source = 0;
393 &set_missing(); # no required keyword yet
394 next LINE;
395 }# end if
396
397 # Beginning of internal prologue
398 # ------------------------------
399 if ($Fld[1] eq $bopi_string) {
400 if ($opt_i) {$prologue = 0;}
401 else {
402 if ($source) { &do_eoc(); }
403 print ' ';
404 print '%/////////////////////////////////////////////////////////////';
405 &do_beg();
406 if ($first ==0) {
407 ### print "\\newpage";
408 print " ";
409 print "\\mbox{}\\hrulefill\\";
410 print " ";}
411 else {
412 unless($opt_b){print "\\section{Routine/Function Prologues} \\label{app:ProLogues}";}
413 }# endif
414 $first = 0;
415 $prologue = 1;
416 $verb = 0;
417 $source = 0;
418 &set_missing(); # no required keyword yet
419 next LINE;
420 }# endelse
421 }# endif
422
423 # A new subroutine/function
424 # -------------------------
425 if ($Fld[2] eq '!ROUTINE:' ) {
426 if ($prologue) {
427 shift @Fld;
428 shift @Fld;
429 $_ = join(' ', @Fld);
430 $name_is = $_;
431 s/_/\\_/g; # Replace "_" with "\_"
432 if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
433 unless ($opt_f) {printf "\\subsubsection{%s (Source File: %s)}\n\n", $_, $FileBaseName;}
434 else {printf "\\subsubsection{%s }\n\n", $_;}
435 $have_name = 1;
436 $not_first = 1;
437 next LINE;
438 }# end if
439 }# end if
440
441 # A new Module
442 # ------------
443 if ($Fld[2] eq '!MODULE:' ) {
444 if ($prologue) {
445 shift @Fld;
446 shift @Fld;
447 $_ = join(' ', @Fld);
448 $name_is = $_;
449 s/_/\\_/g; # Replace "_" with "\_"
450 if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
451 unless($opt_f) {printf "\\subsection{Fortran: Module Interface %s (Source File: %s)}\n\n", $_, $FileBaseName;}
452 else {printf "\\subsection{Fortran: Module Interface %s }\n\n", $_;}
453 $have_name = 1;
454 $have_intf = 1; # fake it, it does not need one.
455 $not_first = 1;
456 next LINE;
457 }# end if
458 }# end if
459
460 # A new include file
461 # ------------------
462 if ($Fld[2] eq '!INCLUDE:' ) {
463 if ($prologue) {
464 shift @Fld;
465 shift @Fld;
466 $_ = join(' ', @Fld);
467 $name_is = $_;
468 s/_/\\_/g; # Replace "_" with "\_"
469 if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
470 unless($opt_f) {printf "\\subsubsection{Include File %s (Source File: %s)}\n\n", $_, $FileBaseName;}
471 else {printf "\\subsubsection{Include File %s }\n\n", $_;}
472 $have_name = 1;
473 $have_intf = 1; # fake it, it does not need one.
474 $not_first = 1;
475 next LINE;
476 }# end if
477 }# end if
478
479 # A new INTERNAL subroutine/function
480 # ----------------------------------
481 if ($Fld[2] eq '!IROUTINE:') { # Internal routine
482 if ($prologue) {
483 shift @Fld;
484 shift @Fld;
485 $_ = join(' ', @Fld);
486 $name_is = $_;
487 s/_/\\_/g; # Replace "_" with "\_"
488 @words = split " ", $_;
489 printf "\\subsubsection [$words[1]] {$_}\n\n";
490 $have_name = 1;
491 next LINE;
492 }# end if
493 }# end if
494
495 # A new CLASS
496 # ------------
497 if ($Fld[2] eq '!CLASS:' ) {
498 if ($prologue) {
499 shift @Fld;
500 shift @Fld;
501 $_ = join(' ', @Fld);
502 $name_is = $_;
503 s/_/\\_/g; # Replace "_" with "\_"
504 if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
505 unless($opt_f) {printf "\\subsection{C++: Class Interface %s (Source File: %s)}\n\n", $_, $FileBaseName;}
506 else {printf "\\subsection{C++: Class Interface %s }\n\n", $_;}
507 $have_name = 1;
508 $have_intf = 1; # fake it, it does not need one.
509 $not_first = 1;
510 next LINE;
511 }# end if
512 }# end if
513
514 # A new Method
515 # -------------------------
516 if ($Fld[2] eq '!METHOD:' ) {
517 if ($prologue) {
518 shift @Fld;
519 shift @Fld;
520 $_ = join(' ', @Fld);
521 $name_is = $_;
522 s/_/\\_/g; # Replace "_" with "\_"
523 if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
524 unless ($opt_f) {printf "\\subsubsection{%s (Source File: %s)}\n\n", $_, $FileBaseName;}
525 else {printf "\\subsubsection{%s }\n\n", $_;}
526 $have_name = 1;
527 $not_first = 1;
528 next LINE;
529 }# end if
530 }# end if
531
532 # A new function
533 # -------------------------
534 if ($Fld[2] eq '!FUNCTION:' ) {
535 if ($prologue) {
536 shift @Fld;
537 shift @Fld;
538 $_ = join(' ', @Fld);
539 $name_is = $_;
540 s/_/\\_/g; # Replace "_" with "\_"
541 if ( $opt_n && $not_first ) { printf "\\newpage\n"; }
542 unless ($opt_f) {printf "\\subsubsection{%s (Source File: %s)}\n\n", $_, $FileBaseName;}
543 else {printf "\\subsubsection{%s }\n\n", $_;}
544 $have_name = 1;
545 $not_first = 1;
546 next LINE;
547 }# end if
548 }# end if
549
550 # Description: what follows will be regular LaTeX (no verbatim)
551 # -------------------------------------------------------------
552 if (/!DESCRIPTION:/) {
553 if ($prologue) {
554 if ($verb) {
555 printf "\\end{verbatim}";
556 printf "\n{\\sf DESCRIPTION:\\\\ }\n\n";
557 $verb = 0; }
558 else { # probably never occurs
559 }# end if
560 if ($opt_x) {
561 printf "\\begin{verbatim} ";
562 $verb = 1;
563 $first_verb = 1; }
564 else {
565 for ($i = 3; $i <= $#Fld; $i++) {
566 printf '%s ', $Fld[$i];
567 }# end for
568 }# end if
569 ### print " ";
570 $have_desc = 1;
571 next LINE;
572 }# end if
573 }# end if
574
575 # Handle optional keywords (these will appear as verbatim)
576 # --------------------------------------------------------
577 if ($prologue) {
578 KEY: foreach $key ( @keys ) {
579 if ( /$key/ ) {
580 if ($verb) {
581 printf "\\end{verbatim}";
582 $verb = 0; }
583 else {
584 printf "\n\\bigskip";
585 }# end if
586 $k = sprintf('%s', $key);
587 $ln = length($k);
588 ###printf "\\subsubsection*{%s}\n", substr($k, 2, $ln - 1);
589 ###printf "{\\Large \\em %s}\n", ucfirst lc substr($k, 2, $ln - 1);
590 $_ = $key;
591 if( /USES/ || /INPUT/ || /OUTPUT/ || /PARAMETERS/ ||
592 /VALUE/ || /ARGUMENTS/ ) {
593 printf "{\\em %s}\n", substr($k, 2, $ln - 1); } # italics
594 else {
595 printf "{\\sf %s}\n", substr($k, 2, $ln - 1); # san serif
596 }# end if
597
598 printf "\\begin{verbatim} ";
599 $verb = 1;
600 $first_verb = 1;
601 if ( $key eq "!INTERFACE:" ) { $have_intf = 1; }
602 if ( $key eq "!CALLING SEQUENCE:" ) { $have_intf = 1; }
603 if ( $key eq "!REVISION HISTORY:" ) { $have_hist = 1; }
604 next LINE;
605 }# end if
606 }# end foreach
607 }# end if
608
609 # End of prologue
610 # ---------------
611 if ($Fld[1] eq $eop_string) {
612 if ($verb) {
613 print "\\end{verbatim}";
614 $verb = 0;
615 }# end if
616 $prologue = 0;
617 # &check_if_all_there(); # check if all required keywords are there.
618 if ( $opt_l ) {
619 $Fld[1] = $boc_string;}
620 else { next LINE; }
621 }# end if
622
623 unless ( $opt_s ) {
624
625 # End of Internal Prologue
626 # ------------------------
627
628 if ($Fld[1] eq $eopi_string) {
629 if ($verb) {
630 print "\\end{verbatim}";
631 $verb = 0;
632 }# endif
633 $prologue = 0;
634 # &check_if_all_there(); # check if all required keywords are there.
635 if ($opt_l) {
636 $Fld[1] = $boc_string;}
637 else { next LINE; }
638 }# endif
639
640 #
641 # Beginning of source code section
642 # --------------------------------
643 if ($Fld[1] eq $boc_string) {
644 print ' ';
645 print '%/////////////////////////////////////////////////////////////';
646 $first = 0;
647 $prologue = 0;
648 $source = 1;
649 ### printf "\\subsubsection*{CONTENTS:}\n\n", $Fld[3];
650 printf "{\\sf CONTENTS:}";
651 printf "\n \\begin{verbatim}\n";
652 $verb = 1;
653 next LINE;
654 }# end if
655
656 # End of source code
657 # ------------------
658 if ($Fld[1] eq $eoc_string) {
659 &do_eoc();
660 $prologue = 0;
661 next LINE;
662 }# end if
663 }# end unless
664
665 # Prologue or Introduction, print regular line (except for !)
666 # -----------------------------------------------------------
667 if ($prologue||$intro) {
668 if ( $verb && $#Fld == 1 && ( $Fld[1] eq $comment_string ) ) {
669 next LINE; # to eliminate excessive blanks
670 }# end if
671 if ( $Fld[2] eq "\\ev" ) { # special handling
672 $_ = $comment_string . " \\end{verbatim}";
673 }# end if
674 s/^$comment_string/ /; # replace comment string with blank
675 # $line = sprintf('%s', $_); # not necessary -- comment str is absent
676 # $ln = length($line); # not necessary -- comment str is absent
677 unless ( $first_verb ) { printf "\n "; }
678 printf '%s', $_;
679 # printf '%s', substr($line, 1, $ln - 1); # comment str is absent
680 $first_verb = 0;
681 next LINE;
682 }# end if
683
684 # Source code: print the full line
685 # --------------------------------
686 if ($source) {
687 print $_;
688 next LINE;
689 }# end if
690
691 }# end inner loop for processing each line of the input file
692 # ---------------------------------------------------------
693
694 }# end main loop for each command-line argument
695 # --------------------------------------------
696 print $_;
697 if ( $source ) { &do_eoc(); }
698 print '%...............................................................';
699
700 # see comment above where these are originally set.
701 #print "\\setlength{\\parskip}{\\oldparskip}";
702 #print "\\setlength{\\parindent}{\\oldparindent}";
703 #print "\\setlength{\\baselineskip}{\\oldbaselineskip}";
704
705 unless ( $opt_b ) {
706 print "\\end{document}";
707 }#end unless
708
709
710 #----------------------------------------------------------------------
711
712 sub CheckOpts
713 # Checks options against a given list. Outputs error message
714 # for any invalid option.
715 #
716 # Usage:
717 # $rc = &CheckOpts ( options, valid_reg_options,
718 # valid_sw_options,
719 # quiet_mode )
720 #
721 # character: options - options to be checked. (e.g. -df+x) The
722 # list must begin with a positive or
723 # negative sign. If no sign appears at the
724 # beginning or by itself, then the argument
725 # is not recognized as a list of options.
726 # character: valid_reg_options - list of valid regular options.
727 # (i.e. options that are associated only
728 # eith negative sign.)
729 # character: valid_sw_options - list of valid switch options.
730 # (i.e. options that can be associated with
731 # either a positive or negative sign.
732 # logical: quiet mode (optional) If true then print no error
733 # messages.
734 # integer: rc - return code
735 # = -1 if the arguement, options, is
736 # not recognized as a list of options
737 # = 0 if all options are valid.
738 # > 0 for the number of invalid options.
739 #
740 { local($options,
741 $valid_reg_options,
742 $valid_sw_options,
743 $quiet_mode ) = @_;
744
745 if ( $options eq "+" ||
746 $options eq "-" ) {return -1}
747
748 local(@Options) = split( / */, $options );
749 if ( $Options[ $[ ] ne "-" &&
750 $Options[ $[ ] ne "+" ) {return -1;}
751
752 local($option, $option_sign, $valid_list, $pos);
753 local($errs) = 0;
754 foreach $option ( @Options ) {
755 if ( $option eq "-" ||
756 $option eq "+" ) {$option_sign = $option;}
757 else {
758 if ( $option_sign eq "-" )
759 { $valid_list = $valid_reg_options
760 . $valid_sw_options; }
761 else
762 { $valid_list = $valid_sw_options; }
763 $pos = index ($valid_list,$option);
764 if ( $pos < $[ &&
765 $quiet_mode ) {
766 $errs++;
767 print STDERR "Invalid option: $option_sign$option \n";
768
769 }# end if
770 }# end if
771 }# end foreach
772 return $errs;
773
774 }#end sub GetOpts
775
776 sub GetOpts
777 # Gets options. If an option is valid, then opt_[option] is
778 # set to 0 or 1 as a side effect if the option is preceeded by
779 # a positive or negative sign.
780 #
781 # Usage:
782 # $rc = &GetOpts ( options, valid_options )
783 #
784 # character: options - options to be checked. (e.g. -df+x) The
785 # list must begin with a positive or
786 # negative sign. If no sign appears at the
787 # beginning or by itself, then the argument
788 # is not recognized as a list of options.
789 # character: valid_options - list of valid options (e.g. dfhx)
790 # integer: rc - return code
791 # = -1 if the arguement, options, is
792 # not recognized as a list of options.
793 # = 0 otherwise
794 #
795 { local($options,$valid_options) = @_;
796
797 if ( $options eq "+" ||
798 $options eq "-" ) {return -1}
799
800 local(@Options) = split( / */, $options );
801 if ( $Options[ $[ ] ne "-" &&
802 $Options[ $[ ] ne "+" ) {return -1;}
803
804 local($option, $option_sign);
805
806 foreach $option ( @Options ) {
807
808 if ( $option eq "-" ||
809 $option eq "+" ) {
810 $option_sign = $option; }
811
812 else {
813
814 if ( index ($valid_options,$option) >= $[ ) {
815 if ( $option_sign eq "-" ) {${"opt_$option"} = 1;}
816 if ( $option_sign eq "+" ) {${"opt_$option"} = 0;};
817
818 }# end if
819 }# end if
820 }# end foreach
821
822 return 0;
823 }#end sub GetOpts
824
825 sub SetOpt
826 # Sets option flags. For the last input option that is in a
827 # list, the flag opt_[option] is set to 1 as a side effect.
828 # For all other options in the list, opt_[option] is set to 0.
829 #
830 # Usage:
831 # $rc = &SetOpt ( options, valid_options )
832 #
833 # character: options - options to be checked. (e.g. -df+x) The
834 # list must begin with a positive or
835 # negative sign. If no sign appears at the
836 # beginning or by itself, then the argument
837 # is not recognized as a list of options.
838 # character: valid_options - list of valid options (e.g. def )
839 # integer: rc - return code
840 # = -1 if the arguement, options, is
841 # not recognized as a list of options.
842 # = 0 otherwise
843 # Note: For the examples provided for the input arguments,
844 # $opt_d = 0, $opt_e = 0, and $opt_f = 1, since the
845 # input option, -f, was the last in the argument,
846 # option.
847 #
848 { local($options,$valid_options) = @_;
849
850 if ( $options eq "+" ||
851 $options eq "-" ) {return -1}
852
853 local(@Options) = split( / */, $options );
854 local(@ValidOptions) = split( / */, $valid_options );
855 if ( $Options[ $[ ] ne "-" &&
856 $Options[ $[ ] ne "+" ) {return -1;}
857
858 local($option, $option_sign);
859
860 foreach $option ( @Options ) {
861 if ( $option ne "-" &&
862 $option ne "+" ) {
863
864 if ( index ($valid_options,$option) >= $[ ) {
865 foreach $valid_option (@ValidOptions ) {
866 ${"opt_$valid_option"} = 0;
867
868 }# end foreach
869 ${"opt_$option"} = 1;
870 }# end if
871 }# end if
872 }# end foreach
873
874 return 0;
875 }#end sub SetOpt
876
877 sub print_help {
878
879 print "Usage: protex [-hbACFS] [+-nlsxf] [src_file(s)]";
880 print " ";
881 print " Options:";
882 print " -h Help mode: list command line options";
883 print " -b Bare mode, meaning no preamble, etc.";
884 print " +-n New Page for each subsection (wastes paper)";
885 print " +-l Listing mode, default is prologues only";
886 print " +-s Shut-up mode, i.e., ignore any code from BOC to EOC";
887 print " +-x No LaTeX mode, i.e., put !DESCRIPTION: in verbatim mode";
888 print " +-f No source file info";
889 print " -A Ada code";
890 print " -C C++ code";
891 print " -F F90 code";
892 print " -7 F77 code";
893 print " -S Shell script";
894 print " ";
895 print " The options can appear in any order. The options, -h and -b,";
896 print " affect the input from all files listed on command-line input.";
897 print " Each of the remaining options effects only the input from the";
898 print " files listed after the option and prior to any overriding";
899 print " option. The plus sign turns off the option.";
900 }# end sub print_help
901
902 sub print_notice {
903
904 print "% **** IMPORTANT NOTICE *****" ;
905 print "% This LaTeX file has been automatically produced by ProTeX v. 1.1";
906 print "% Any changes made to this file will likely be lost next time";
907 print "% this file is regenerated from its source. Send questions ";
908 print "% to Arlindo da Silva, dasilva\@gsfc.nasa.gov";
909 print " ";
910
911 }# sub print_notice
912
913 sub print_preamble {
914
915 unless ( $opt_b ) {
916 print "%------------------------ PREAMBLE --------------------------";
917 print "\\documentclass[11pt]{article}";
918 print "\\usepackage{amsmath}";
919 print "\\usepackage{epsfig}";
920 print "\\usepackage{hangcaption}";
921 print "\\textheight 9in";
922 print "\\topmargin 0pt";
923 print "\\headsep 1cm";
924 print "\\headheight 0pt";
925 print "\\textwidth 6in";
926 print "\\oddsidemargin 0in";
927 print "\\evensidemargin 0in";
928 print "\\marginparpush 0pt";
929 print "\\pagestyle{myheadings}";
930 print "\\markboth{}{}";
931 print "%-------------------------------------------------------------";
932 }# end unless
933
934 # in your main document before you include any protex-generated files
935 # for the first time, if you define these three variables as length
936 # settings (like this:)
937 # \newlength{\oldparskip}
938 # \newlength{\oldparindent}
939 # \newlength{\oldbaselineskip}
940 # then 1) comment in all the lines below, and 2) find the 3 reset lines
941 # further down and comment in them as well.
942 # then protex will override the paragraph and skip settings during
943 # the source sections, but will restore the original document settings
944 # at the end. if someone can figure out how to check to see if a
945 # latex variable exists, and do a conditional section, we could make
946 # this fully self-contained.
947 # nsc feb 2003
948
949 #print "\\setlength{\\oldparskip}{\\parskip}";
950 print "\\setlength{\\parskip}{0pt}";
951 #print "\\setlength{\\oldparindent}{\\parindent}";
952 print "\\setlength{\\parindent}{0pt}";
953 #print "\\setlength{\\oldbaselineskip}{\\baselineskip}";
954 print "\\setlength{\\baselineskip}{11pt}";
955
956 }# end sub print_preamble
957
958 sub print_macros {
959
960 print " ";
961 print "%--------------------- SHORT-HAND MACROS ----------------------";
962 print "\\def\\bv{\\begin{verbatim}}";
963 print "\\def\\ev\{\\end\{verbatim}}";
964 print "\\def\\be{\\begin{equation}}";
965 print "\\def\\ee{\\end{equation}}";
966 print "\\def\\bea{\\begin{eqnarray}}";
967 print "\\def\\eea{\\end{eqnarray}}";
968 print "\\def\\bi{\\begin{itemize}}";
969 print "\\def\\ei{\\end{itemize}}";
970 print "\\def\\bn{\\begin{enumerate}}";
971 print "\\def\\en{\\end{enumerate}}";
972 print "\\def\\bd{\\begin{description}}";
973 print "\\def\\ed{\\end{description}}";
974 print "\\def\\({\\left (}";
975 print "\\def\\){\\right )}";
976 print "\\def\\[{\\left [}";
977 print "\\def\\]{\\right ]}";
978 print "\\def\\<{\\left \\langle}";
979 print "\\def\\>{\\right \\rangle}";
980 print "\\def\\cI{{\\cal I}}";
981 print "\\def\\diag{\\mathop{\\rm diag}}";
982 print "\\def\\tr{\\mathop{\\rm tr}}";
983 print "%-------------------------------------------------------------";
984
985 }# end sub print_macros
986
987 sub do_beg {
988 unless ( $opt_b ) {
989 if ( $begdoc == 0 ) {
990 if ( $tpage ) {
991 print "\\title{@title}";
992 print "\\author{{\\sc @author}\\\\ {\\em @affiliation}}";
993 print "\\date{@date}";
994 }
995 print "\\begin{document}";
996 if ( $tpage ) {
997 print "\\maketitle";
998 }
999 print "\\tableofcontents";
1000 print "\\newpage";
1001 $begdoc = 1;
1002 }
1003 }
1004 }# end sub do_beg
1005
1006 sub do_eoc {
1007 print ' ';
1008 if ($verb) {
1009 print "\\end{verbatim}";
1010 $verb = 0;
1011 }
1012 $source = 0;
1013 }# end sub do_eoc
1014
1015 sub set_missing {
1016
1017 $have_name = 0; # have routine name?
1018 $have_desc = 0; # have description?
1019 $have_intf = 0; # have interface?
1020 $have_hist = 0; # have revision history?
1021 $name_is = "UNKNOWN";
1022
1023 }# end sub set_missing
1024
1025
1026 sub check_if_all_there {
1027
1028 $have_name ||
1029 die "ProTeX: invalid prologue, missing !ROUTINE: or !IROUTINE: in <$name_is>";
1030
1031 $have_desc ||
1032 die "ProTeX: invalid prologue, missing !DESCRIPTION: in <$name_is>";
1033
1034 $have_intf ||
1035 die "ProTeX: invalid prologue, missing !INTERFACE: in <$name_is>";
1036
1037 $have_hist ||
1038 die "ProTeX: invalid prologue, missing !REVISION HISTORY: in <$name_is>";
1039
1040 }# end sub check_if_all_there

  ViewVC Help
Powered by ViewVC 1.1.22