JACOsub Quick Reference
=======================

This document serves as a brief summary to JScripts.doc.  Refer to
JScripts.doc for complete details.


SCRIPT COMPILER COMMANDS
========================

#  (followed by a space) Comment.  The line will be ignored.

#C[LOCKPAUSE] <time>
   Force clock to pause at time specified while playing.  Keypress resumes.

#D[IRECTIVE][n] <directive string>
   Change default directive n.  n=0 (overall directive) if n omitted.
   n may range from 0 to 9.

#F[ONT] <n> <fontname.font> <h> [CLEAN or QUICK&DIRTY] [Y/X]
   Set font n to fontname.font, h pixels tall.  n may range from 0 to 9.
   Mono fonts are always QUICK&DIRTY (rendered fast).
   For face colors other than 3, color fonts default to CLEAN (rendered
   one character at a time), unless QUICK&DIRTY is specified.
   Y/X is used to change the aspect ratio from 1/1 (AmigaDOS 2.0+).

#I[NCLUDE] <time> <filename>
   Include script file <filename> into the current script, offsetting
   the new script's start time by the time specified.  Offset cannot be
   negative.  Offset units depend on time units set by #TIMERES.
   #F, #P, #Q, and #R in an included script will be ignored.
   The effects of #D, #S, and #T are passed down into included scripts.

#P[ALETTE] <color> <r> <g> <b> [palette]
   For specified color register, set RGB intensities (0 to 15).  palette
   defaults to 0 (primary palette), but may be 0 through 9.  Use palettes
   1 - 9 with the CP directive.

#Q[UANTIZE][n]
   Eliminate timing gaps between subtitles of less than n time units.
   Number of time units per second is specified by #TIMERES.

#R[AMP] <seconds.units>
   Adjust script play for time drift by changing the script's overall
   running time.  Positive ramp adjustments lengthen the play, negative
   adjustments shorten it.  Time units are determined by #TIMERES.

#S[HIFT] <[[hours:]minutes:]seconds.units>
   Shift all times in script by the amount specified.  Positive shifts
   delay time events, negative shifts advance them.

#T[IMERES] <n>
   Set time resolution of script to n units per second.  Default is 30
   if this command does not appear in the script.
ESCAPE CODES TO EMBED IN TITLES
===============================

\   Concatenate.  Assume next line in script continues current title.
    Leading and trailing spaces in concatenated lines are ignored.

\n  Newline.  Use to split a title text into multiple lines.  \n codes
    override wordwrapping, but the resulting text substrings might still
    be individually wordwrapped if needed.

\{  Display a left brace, which is normally used to begin a non-displaying
    comment embedded in the title.

\~  Display a tilde, which is normally used to create a "hard" non-
    wrappable space.

\\  Display a backslash, which is normally used to begin an escape code.

\N  Normal.  Display text that follows in "normal" style.  Equivalent to
    the SN directive.

\I  Italics. Display text that follows in italics.  Equivalent to the SI
    directive.

\B  Boldface.  Display text that follows in boldface (sometimes useful).
    Equivalent to the SB directive.

\U  Underline.  Underline text that follows (not useful).  Equivalent to
    the SU directive.

    Note: /N, /I, /B, and /U are mutually exclusive.

\Cn Color n.  Use face color n for text that follows.  n is a hexadecimal
    digit ranging from 0 to 9 and A to F (or a to f).  Equivalent to the
    CF directive.

\Fn Font n.  Use font n (0 to 9) for text that follows.  Equivalent to the
    F directive.
TITLE DIRECTIVES
================
Directives occur after the stop time is specified.  You may omit the title
directive if you title begins with a non-alphabet character (such as a left
brace for a {comment}), in which case the directive defaults to D.

Vertical positioning
--------------------

  VA
     Vertical continuation Above previous title, using previous title's
     vertical positioning setting.  Opposite of VU.

  VB[n]
     Vertical Bottom, offset from bottom of display by n pixels.  n may
     be omitted (default n, usually 16, can be set with the #D command).

  VHn
     Vertical line Height n% of normal.  VH200 makes double-spaced lines.

  VL[n]
     Vertical Line position n.  Line height depends on font size.  If n is
     negative or omitted, vertical line position will be where the previous
     timed line started.

  VM[n]
     Vertical Middle.  Center vertically between VTn and VBn position.
     n=0 by default, otherwise shifts block up or down n text lines.

  VPn
     Vertical Pixel position n.  Baseline of font will be n pixels from
     top of display.

  VSn
     Not yet implemented; doesn't do anything yet.  Don't ask.

  VT[n]
     Vertical Top, offset from top of display by n pixels.  n may be
     omitted (default n, ususally 16, can be set with the #D command).

  VU
     Vertical continuation Under previous title, using previous title's
     vertical positioning setting.  Opposite of VA.

Horizontal positioning
----------------------

 Margins:

  HLn
     Horizontal Left margin n% of display width from left edge.

  HRn
     Horizontal Right margin n% of display width from right edge.

 Text justification:

  JC
     Justify Center.  Text is centered within HLn - HRn constraints.

  JF[:p]
     Justify Full.  Aligns left and right edges with the ends of the
     widest line in the text box.  Last line in block is unaffected, except
     to position it Left, Right, or Center (default), when :p is :L, :R, or
     :C, respectively.  JF:U means Unconditional justification -- ALL lines
     in the block will be stretched to fit exactly within the margins.

  JL
     Justify Left.  Align left edge of text at the HLn margin position.

  JR
     Justify Right.  Align right edge of text at the HRn margin position.

 Block justification:

  JBC
     Justify Block Center.  Position the text, after wordrwapping, so that
     it is centered within the margins, preserving the text justification.
     To get "AnimEigo" positioning, use JBC with JL.

  JBF
     Justify Block Full.  Cancel the effect of any JB directive if one
     happens to be in use as a default directive.

  JBL
     Justify Block Left.  Position the text block at the left margin.

  JBR
     Justify Block Right.  Position the text block so that the right
     edge is at the right margin, preserving the text justification.

 Word wrapping:

  W0
     Disable automatic word wrapping.  Warning: text may overflow screen
     boundaries.

  W1
     Automatic "smart" word wrapping (default).  Wrap text so that the
     screen area consumed by the title is minimized.

  W2
     Automatic "stupid" (generally known as "greedy") word wrapping.
     Fit as much text into a line as possible without regard to appearance
     or screen space consumed.

Fonts
-----

 Font rendering:

  Fn
     Use font n (0 - 9) for the title text.

  FQ
     Force title to be rendered Quick&Dirty.  Mono-color fonts and
     colorfonts using color 3 are always quick anyway.

  FC
     Force title to be rendered Clean (1 character at a time) to avoid font
     shadow overlap interference problems.rendering.  Mono-color fonts and
     colorfonts using color 3 will still be rendered fast.

  FD
     Force Default text rendering.  Used to override a global #DFC or #DFF
     command.

  FOn[:a]
     Generate Font Outline n pixels wide, optionally use antialias color a.
     Warning:  This slows the program down considerably.

  FSdn
     Generate Font Shadow in direction d (one of 8 compass directions
     N, S, E, W, NW, NE, SW, SE), n pixels deep.

 Font style (may also be set with \ codes in the title text):

  SN
     Normal style (typical default).

  SI
     Italic.

  SB
     Bold (using the JACOsub font, this looks best with color 3).

  SU
     Underline (ugly!  Not recommended).

 Color

  CFn
     Color Fontface n.

  CBn
     Color Background n.  Screen is cleared to color n prior to rendering
     anything to it.  Useful for creating a genlock-opaque background if
     n is nonzero.

  CPn
    Load Color Palette n (0 to 9, set with #PALETTE command) at the start
    time of this title.  If you can see the palette change after the
    display is updated, precede your alternate palette lines with a "dummy"
    short-duration blank screen (containing a hard space) using your
    alternate palette.

  CS[L]n[:s[:c]]
    Color Shaded box with n-pixel margin around text, using shade style :s
    (:0=pattern, :1=solid color), using optional color :c (normal default
    is :2 [black], can be re-set with a #D command).  Titles that overlap
    in time AND use the CS directive will be surrounded by a SINGLE box; if
    CSL is used, a box will appear around individual lines (including
    segments resulting from wordwrapping).  n=0 disables shading.

Genlock fader control
---------------------

  GBn[Tm]
    Genlock Background n% of saturation in m/60 seconds.  m=0 if Tm is
    omitted.  n=0 is a transparent background.

  GGn[Tm]
    Genlock Graphics n% of saturation in m/60 seconds.  m=0 if Tm omitted.
    n=100 is full-on graphics.

  Note:  Do not use the G directives in the global #D command.

IFF graphic files
-----------------

  IL <ILBM file name> [<x offset %> <y offset %>]
    Load an IFF ILBM bitmap into the video screen for the time interval
    specified by this line's start and stop time.  Current screen colors
    will be used; the IFF colors will be ignored.  x and y are percents of
    screen width and height to offset the center of the bitmap from the
    center of the screen.  Through overlapping time ranges, as many as
    40 images may be loaded onto a single screen, memory permitting.
    Text can appear concurrently with the bitmaps.

  IS <ILBM file name>
    Load an IFF ILBM file into its own screen, using the file's own
    resolution and colors.  Text cannot appear concurrently.

  Note:  Do not use the I directives in the global #D command.

ARexx communications
--------------------

  RX <ARexx script name>
    Execute the ARexx script name that follows the RX directive.  Do not
    specify other directives on the same line, and have no more than one
    RX directive per time event.

  Note:  Do not use the RX directive in the global #D command.

Default directives
------------------

  D or D0
    Default 0verall.  To be used if no other directives are used.  The
    behavior of D can be set with the #D command.

  Dn
    Default alternate n (1 - 9).  Use these for "shortcuts" to long
    directive strings that you like to use repeatedly.  Set with the #D
    command.