share/contrib/gentran/man/sect1.ms

   1 .NH 1
   2 INTRODUCTION
   3 .LP
   4 Solving a problem in science or engineering is often a two-step
   5 process.  First the problem is modeled mathematically and derived
   6 symbolically to provide a set of formulas which describe how to
   7 solve the problem numerically.  Next numerical programs are
   8 written based on this set of formulas to efficiently
   9 compute specific values for given sets of input.  Computer algebra
  10 systems such as MACSYMA /9,10/ provide powerful tools for use in the
  11 formula-derivation phase but only provide primitive program-coding
  12 tools.  The GENTRAN package has been constructed to automate
  13 the tedious, time consuming and error-prone task of writing numerical
  14 programs based on a set of symbolic expressions.
  15 .NH 2
  16 The GENTRAN Code Generator and Translator
  17 .LP
  18 The GENTRAN code GENeration and TRANslation package /4,5/, originally
  19 implemented in Franz LISP /3,14/ to run under VAXIMA /2/, has also been
  20 implemented in RLISP to run under REDUCE /6/.  Although GENTRAN
  21 was originally created specifically to generate numerical
  22 code for use with an existing FORTRAN-based finite element analysis
  23 package /12,13/, it was designed to provide the flexibility
  24 required to handle most code generation
  25 applications.  GENTRAN contains code generation functions, file-handling
  26 functions, mode switches, and global variables, all of which are
  27 accessible from both the user level and the LISP level of VAXIMA to
  28 give the user maximal control over the code generation process.  Formatted
  29 FORTRAN /1/, RATFOR /7/ or C /8/ code can be generated from
  30 algorithmic specifications,
  31 i.e., descriptions of the behavior of the target numerical program expressed
  32 in the VAXIMA programming language, and from symbolically derived expressions
  33 and formulas.
  34 .LP
  35 In addition to arithmetic expressions and assignment statements,
  36 GENTRAN can also generate type declarations and control-flow
  37 structures.  Code generation can be guided by user-supplied
  38 template file(s) to insert generated code into pre-existing program
  39 skeletons, or it can be accomplished interactively through a series
  40 of translation commands without the use of template files.  Special
  41 mode switches enable the user to turn on or off specific features such as
  42 automatic segmentation of large expressions, and global variables
  43 allow the user to modify the code formatting process.  Generated
  44 code can be sent to one or more files and, optionally, to
  45 the user's terminal.  Stacks of open I/O channels facilitate temporary
  46 output redirection and recursive invocation of the code generation process.
  47 .NH 2
  48 Organization of the Manual
  49 .LP
  50 The remainder of this manual is divided into five sections.  Sections
  51 2 and 3 describe code generation.  Section 2 explains interactive code
  52 generation, the expression segmentation facility, code optimization,
  53 and how temporary
  54 variables can be generated; then section 3 explains how code generation
  55 can be guided by a user-supplied template file.  Section 4 describes
  56 file-handling functions which control output redirection,
  57 and section 5 describes
  58 user-accessible global variables and mode switches which alter the code
  59 generation process.  Finally, section 6 presents three complete examples.
  60 .LP
  61 Throughout this manual, examples are given from both the user
  62 and the LISP levels of VAXIMA.  It is assumed that the user knows
  63 that a <control>D typed at the user level puts VAXIMA into LISP
  64 mode and vice versa, and that programming at the LISP level is in
  65 Franz LISP.
  66 .NH 3
  67 Typographic Conventions
  68 .LP
  69 The following conventions are used in the syntactic definitions of
  70 functions throughout this manual:
  71 .IP -
  72 Command parts which must be typed exactly as shown are \fIunderlined\fR.
  73 .IP -
  74 User-supplied arguments are not underlined.
  75 .IP -
  76 { ... } indicate optional command parts and are not actually part of
  77 the function call syntax.
  78 .LP
  79 The syntax of each GENTRAN function is shown terminated with a
  80 \fB;\fR.  However, either \fB;\fR or \fB$\fR can be used to terminate any
  81 command with the usual VAXIMA meaning:  \fB;\fR indicates that the
  82 returned value is to be printed, while \fB$\fR indicates that printing
  83 of the returned value is to be suppressed.