Documentation for ce-conv.c
version 1.0, May 1991
version 1.1, Aug 1991
The program ce-conv reads text descriptions of Cosmic Encounter powers
and their associated Flares either from standard input or from a list
of files given on the command line and generates three files, POWERS.OUT,
FLARES.OUT, and FLARES.ONE, which contain PostScript. When the
PostScript
is combined with the header files powers.ps and cards.ps (distributed
separately), the result can be used to print power cards and Flares.
MAJOR CHANGES IN VERSION 1.1
---------------------------Several bugs fixed.
Ability to process multiple files from command line (re-direction can
also be used).
Ability to define power origin strings in the file.
Power origin is now a string of up to 15 characters.
Alien histories now optional.
Each power may have any number of Flares (each generating a card in the
final PostScript). Each Flare is either multiple-use (Eon) or one-shot
(Mayfair); the two types are emitted into separate files.
USAGE
----To compile under UNIX:
cc -o ce-conv ce-conv.c
To use under UNIX:
ce-conv < file
or
ce-conv file [file ...]
Abnormal exit conditions are indicated by an error message with the
file and line number.
Don't ask me about other systems. It's all (pre-ANSI) C, using only
the stdio library for input, output, and file creation; it should run
on any box with a C compiler, but I'm not guaranteeing anything.
INPUT FILE FORMATS
------------------
Each input file consists of a header followed by a number of text
records.
All blank lines and lines beginning with a space, tab, or semicolon act
as separators and are ignored; they may be used as comments. Lines are
limited to 256 characters.
HEADER
-----The header consists of a number of string definitions, one per line.
These definitions (suitably processed) will be included in the PostScript
for the power file; the intent is that they be used to define power
origin strings.
Each string definition appears on a single line, with the form:
#origin string
The '#' symbol must appear in the first column. This is immediately
followed (no intervening spaces) by a sequence of up to 15 characters
which gives the origin, a single space, and an arbitrary sequence of
characters terminated by the end of the line. The effect is to cause
PostScript which defines the name Setorigin to be the string. For
example, the line
#Ev2n1 Encounter 2.1
will translate into the PostScript
/SetEv2n1 (Encounter 2.1) def
WARNING: Do not use "up" as an origin. It will interfere with the
routine "Setup" and the effects are unpredictable.
POWER DESCRIPTION FORMAT
-----------------------Following the header are a number of text records, each describing a
Power. Each record consists has two mandatory and two optional
components
followed by zero or more Flare descriptions, each having two components.
Records and components within records are separated by blank lines or
lines beginning with a space, tab, or semicolon.
The first mandatory component is the power line.
with the form
POWERNAME
[T:Origin:R]
This is a single line
POWER DESCRIPTION
The POWERNAME is the Alien name, for example AMOEBA. The name begins
in the first column and is terminated by a tab character (additional
tabs and spaces may be included after the tab character). The name
may contain several words separated by spaces.
The '[' character begins the description of the power type and origin.
The character T should be replaced with M (mandatory power), O
(optional),
or B (both). The word Origin should be replaced with a string of from
one to fifteen characters identifying the Power's origin. The digits 0
through 9 are used for the Eon set (0 representing the original 15
Aliens),
and I have taken the strings W and WashU for "Washington U". All other
strings are free, but do not use any of ()<>[]{}/:%, or whitespace, or
non-printable ASCII. Also, when you use a new origin string, you must
either define the string in the file header (see above) or edit the
powers.ps file and define a PostScript string named "Set%", where % is
replaced by the origin string; for example, to use the W I added the line
/SetW (Washington U) def
to cards.ps; I could also have added the line
#W "Washington U"
to the header of the input file to CE-convert.
The :R section is optional; if present, it lists use restrictions for
the power. The R is replaced with one or more symbols from the
following:
2
A
D
F
H
K
L
M
N
P
T
Do not use in a two-player game
UOW (use only with) Asteroids
UOW Special Destiny
UOW Flares
UOW Hazards
UOW Kickers
UOW Lucre
UOW Moons
UOW Multiple powers ("N"-power game)
UOW Prisoners
UOW Technology
These symbols are used only for the (optional) placement of small icons
on Power cards and Flares to indicate the restriction. They should not
be confused with the use restrictions printed on the power cards.
After the ']' character are zero or more spaces or tabs, followed by the
short power description, for example UNLIMITED TOKEN MOVEMENT. This
description is terminated by the end of the line.
The second mandatory component is the long power description. This
description must begin with "You have the power ", which is followed by
one of "to", "of", "over", or " ", which is followed by the short power
description terminated by a period (i.e., "You have the power to ooze.").
This must all appear on a single line; additional text can follow it on
the line. The strings "to", "of", "over", and " " are defined in a
structure at the beginning of ce-conv.c. Strings may be added to this
structure; corresponding PostScript strings must be defined in cards.ps.
You should give the really short description in lower case; the leading
letters of words in this description (other than "and", "or", "the", "a")
will be converted to upper case for the Flare. Thus, "power to ooze" is
printed on Flares as "Power to Ooze", while "power to store and
discharge"
becomes "Power to Store and Discharge". If you #define CAPITALIZE in
ce-conv.c this will also be done for the Power card.
Following the opening sentence is a paragraph describing the use of the
power.
The third component is the history. This component is optional, but if
present must come after the paragraph describing the power. If present,
this component begins with "History: " (note space after colon) with the
H in the first column and continues with another paragraph of text.
The final component of the power is the use restrictions (e.g, "Use only
in a game with Lucre!"). This component is optional, but if present must
come after the History component. If present, this component begins with
"Restriction: " and continues with a paragraph.
FLARE DESCRIPTION FORMAT
-----------------------Following the components of the power are zero or more Flare
descriptions.
Each Flare description has two components, a Wild Flare and a Super
Flare.
Each component begins with a keyword which must start in the first column
of the line and continues with a paragraph.
There are two types of Flares, multiple-use (Eon-style) and one-shot
(Mayfair-style); these are distinguished by the keywords beginning the
paragraphs. Multiple-use Flares start with "Wild: " and "Super: ",
while one-shot Flares start with "Wild1: " and "Super1: ". You cannot
mix
the two types; a Wild must be followed by a Super, and a Wild1 by a
Super1.
A power may have any combination of Flares, including several Wild and
Super Flares of each type; this will simply result in several cards for
the power. The multiple-use Flares go in the FLARES.OUT file, and the
one-shot Flares go in the FLARES.ONE file.
OUTPUT FILE FORMATS
-------------------
Three files named POWERS.OUT, FLARES.OUT, and FLARES.ONE are created when
the program is run. The first contains PostScript for the Powers in a
form
suitable for use with powers.ps. The second contains PostScript for the
multiple-use Flares in a form suitable for use with cards.ps, and the
third
contains the one-shot Flares. These formats are documented separately.
Note that either or both of the FLARES files may be (effectively) empty,
depending on what Flares are actually present in the file.
CHARACTER CONVERSIONS
--------------------All text is converted into PostScript strings.
interpretations are performed:
The following special
The sequence -- is converted into en dash (PostScript \261).
The sequence ... is converted into ellipsis (\274).
Double quotes " are converted into balanced sets of open and close
double quotes (\252 and \272). This is strictly a toggle; given the
phrase 'Don said, "Bill said, "I saw it""', ce-conv will NOT balance
the quotes in the correct pattern.
Newlines and the sequences "\ " and "\n" are converted into spaces.
Tabs and the sequence "\t" are converted into "\t".
tabs have a width of three spaces.
When printed,
The sequence "\r" is passed unchanged. This generates a carriage return
in the final string, which when "typeset" by the routines in cards.ps
and powers.ps starts a new line.
The sequence "\l" is converted into pounds sterling (\243) (lucre).
The sequences "\b" and "\*" are converted into bullet (\267).
The sequence "\-" is converted into em dash (\320).
The sequence \xxx, where xxx is three octal digits, is passed through
without interpretation; this can be used to put specific PostScript
characters into the strings. See the Adobe manuals for the character
encodings; the routines use the PostScript standard text encodings.
A double backslash "\\" is output unchanged; this produces a single
backslash in the final print.
A backslash followed by any other character is converted into a double
backslash (followed by the same character). This will produce a single
backslash (and the character) in the final print.