FILE ROSE.DOC
 
written:       1992-10-08 <Gerhard.Gonter@wu-wien.ac.at>
latest update: 1993-05-15
 
Note: You guess it, the file is still not very complete ...

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Introduction and Overview:

This file describes the installation procedure ROSE and the format of
files used as the basis for the installation.  The files that are read
are a PRODUCT file and an optional FIX file.  The PRODUCT file contains
all necessary information from the author of the product with all
pre-defined options and help information for the installer.  The
optional FIX file is used to read values for installation parameters
that where used in an earlier installation rundown.  Typically, the
author distributes a PRODUCT file and no FIX file.  Under some
circumstances it might be useful to distribute a set of pre-defined
FIX files together with the PRODUCT file.
 

------------------------
Operation:

To install a product using ROSE enter the following command:
   ROSE productname

The product name is the name of a PRODUCT file, e.g. if you received
VieGOPHER, then enter:
   ROSE VIEGOPHR

When running down the PRODUCT file, ROSE will occasionally prompt you
for selection options.  They are usually presented like this:

  +-------------------------------------------------------------+
  |             (... some other text ...)                       |
  |*****************************************************        |
  |The variable XYZ is used to do ...                           |
  |Allowed values are ABC, DEF or GHI.                          |
  |The predefined value is GHI.                                 |
  |---------                                                    |
  |1. use predefined value: GHI                                 |
  |2. use fixed value:                                          |
  |3. enter new value                                           |
  |X. stop                                                      |
  +-------------------------------------------------------------+

At this point you can select between the options by entering the
code shown in the menu:
1. The predefined value, that is the value that is defined in the
   PRODUCT file in a #set statement.
2. The fixed value, that is the value which was used in the last
   ROSE run-down.  That particular value was loaded from the
   FIX file.
3. A new value.  When this code is selected enter the new value
   that you want to use in your installation on the input line.
X. ... to abort the installation process immediately.

For convenience, two short hand entries are possible:
-  Hitting ENTER alone means to use the predefined value.
   This is equivalent to option 1.
-  Entering anything other than 1, 2, 3, X, x or just ENTER
   means that this value is used a new fix value.
   This is equivalent to option 3.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The PRODUCT file:

Basically, the PRODUCT file contains information for generating the
production modules and formatting information that is used for preparing
the source listing.


Syntax:
 
Lines starting with a # sign are treated as ROSE commands, however
text lines starting with a # sign in column 1 can be generated by
adding an extra # sign in front to the line.
 
general syntax:
#command parameters     ROSE command with optional parameters
# comment               commented text, not to be included
                        in the module generated.
##line                  text line written as #line
#end                    end of product data, processors should not read
                        beyond this statement.
 
1. commands relevant for documentation
#section <text>         generates a LaTeX section
#subsection <text>      generates a LaTeX subsection
#subsubsection <text>   generates a LaTeX subsubsection
#paragraph <text>       generates a LaTeX paragraph
#verbatim               introduces a LaTeX block
#endverbatim            ends a LaTeX block
#v <text>               verbose text, one line
#organize <rose> <latex> <text>         /*not used*/

2. commands relevant for code generation

2.a. conditional output generation
#switch <id>            conditional output generation depending on
                        the value of the variable <id>
#case <val>             output generated if variable <id> has value <val>
#default                output is generated if no #case matched
#endswitch              end of a conditional output generation section

2.b. file handling
#erase <filename>       erase the named file
#module <filename>(opt  append generated output to the named file
                        possible options:
                        FIX: the file is written with fixed records
                             and line numbers

2.c. interaction
#help <id>              begin of help text for a variable <id>
#endhelp
#set <id> <val>         set variable <id> to the value <val>
#prompt <id> <val>*     prompt for fix value for <id>
                        if values (<val>*) are specified, the input
                        is verified against them and only values from
                        the list are accepted.
#call <pgm> <id>*       call the program <pgm> and replace macros
                        for 0 or more ROSE variables <id>.
 
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Remarks:
The program's name origins from Rose Nylund and does *not* mean anything
fancy like 'REXX Output Synthesizer Engine' but I wouldn't mind if anyone
prefers the second version.


+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
To-Do list:
+  hooks: include sections of code provieded by the user
+  suppress option for fixed value if there is none
+  check out option for fixed record length option