JACOsub 2.5r SCRIPT FILE FORMAT SPECIFICATION
=============================================

Here is the complete JACOsub script file format specification.
It's not complicated (unless you want it to be) and quite flexible.
Check out the sample script (demo.js) that came with this software;
it demonstrates many of the things you can do with a script.

The accompanying file QuickRef.doc is a summary of this document, providing
brief descriptions of the commands, escape codes, and directives that you
can put into a script.

CONTENTS OF THIS DOCUMENT
=========================

 1.  Basic format conventions
 2.  Compiler commands
 3.  Timed lines
 4.  Directives (for controlling timed lines)
 5.  Sample lines
 6.  Credits

Most of the information in this document is demonstrated by the timed
script demo.js, which is included in the JACOsub distribution archive.


1.  BASIC FORMAT CONVENTIONS
============================

1.  Space characters (white space) may consist of spaces or tabs.  Any line
    in a script file may contain any amount of white space in front of,
    behind, or in between parameters or words.

2.  A line cannot be more than 511 characters in length (but you can
    concatenate several lines; see "escape codes" below).

3.  Lines in the file may be blank lines, compiler commands, or timed
    lines for the script.  All these are explained below.

4.  Blank lines or lines containing white space only are ignored.


2.  COMPILER COMMANDS
=====================

Any line where # is the first non-space character is treated as a compiler
command.  The command is indicated by the next character or word (upper or
lowercase) following the #.  Some commands have arguments, which are
assumed to begin with the next non-whitespace characters following the
command.  Anything shown here in square brackets [] are optional.
The commands are:

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

           Example:
           # This is a comment.

   #C[LOCKPAUSE] <time>
           While a script is running, this command forces the clock to
           pause the clock at the time specified by <time>.  Pressing a key
           will resume play.  <time> is an offset from the beginning of the
           script in the form H:MM:SS.FF (hours:minutes:seconds.units).
           The beginning time of a script is usually 0:00:00.00 unless the
           script was included with an offset using the #I command.

           This command is useful for titling multiple laserdisc sides in
           a single script.  Be warned:  There will be no indication on the
           screen telling you that the script is paused!  You have to keep
           track of your pauses yourself.

   #D[IRECTIVE][n] <directive string> [optional_name]
           Change some directive defaults (see the Directives section
           below), for example:

           #D CF10F2  small_red_text
           #directive3 hr50vmf2
           #d9JLJBC

           This command affects only those lines following it.  Scripts may
           contain as many #D commands as you like.

           There are 31 default directives available, D0 through D30.
           Specifying #D is the same as #D0 -- this sets the general
           overall default directive when a title line contains no
           directive or when just the D directive is present.  The
           directives D1 - D30 may be set for situations when you need a
           shorthand way to represent a long complicated directive string
           in many places in your script.  Directives D0-D30 are initially
           all identical, according to your DIRECTIVE config setting.

           Instead of a long cryptic directive in your timed lines, you
           may use the short codes you define, like D, D1, D2, etc.
           Alterately, you may also assign sensible names to your directive
           definitions and use these names instead of the codes D3, D4,
           etc.  If you use a directive name instead of the actual
           directive code in your title, you must enclose the name in
           square brackets [].  The name definition in the #D command must
           NOT contain brackets.  The name will be truncated after 20
           characters, and uppercase or lowercase doesn't matter.

   #F[ONT] <n> <fontname.font> <size> [CLEAN or QUICK&DIRTY] [Y/X]
           This command sets font <n> to <fontname.font> which is <size>
           pixels high.  Font settings affect the entire script.  The <n>
           argument may range from 0 to 9 if the software has been
           registered, otherwise <n> may range from 0 to 3.  #F commands
           should be specified before any timed lines in the script.

           CLEAN or QUICK&DIRTY indicate the rendering mode for the font.
           Normally, you should NEVER need to set the rendering mode!  The
           program is smart enough to determine the best mode.  Mono-color
           fonts will always be QUICK&DIRTY, and color fonts will be CLEAN
           only if the characters are designed to overlap.

           The Y/X argument modifies the default 1/1 aspect ratio for the
           font's height vs. width.  It must be specified as two integers
           separated by a slash with no spaces, as in 40/33.  This argument
           works only in AmigaDOS versions 2.0 or higher.

           NOTE:  Due to the Amiga's internal font management, the Y/X
           parameter will affect only those fonts having names and/or sizes
           different from those fonts already loaded in memory.  For
           example, the 36-pixel JACOsub font is loaded as font 0 when the
           program starts up, and its aspect ratio will be whatever it had
           when it loaded (see the FONT setting in the jacosub.cfg file).
           Any attempt to assign "jacosub.font 36" a different aspect will
           have no effect.  You can get around this by setting the program
           configuration so that font 0 is something like Topaz 9,
           rebooting, and then using your script to load jacosub.font 36
           with the desired aspect ratio.

           Example: #F 2 Diamond.font 20

   #H[RES] <resolution mode>
           This sets the horizontal display resolution mode (HIRES or
           SUPERHIRES) that is expected to be used with the script.  This
           should be set in the program configuration; set it in the script
           only if the script is designed specifically for a particular
           resolution mode.  SUPERHIRES will be ignored on computers
           incapable of it.  This command will be ignored if it occurs
           after the first timed line, or inside #Included scripts.
   
   #I[NCLUDE] <time> <filename>
           Include another script file <filename> into the current script,
           offsetting the second script's start time by <time>.  <time> is
           always FORWARD offset.

           This command is useful, for example, if you are subtitling a
           series of TV shows having subtitles for credits and ending song
           lyrics.  Rather than importing and/or re-timing the same
           sequences over and over again for each episode, you need only
           time the song lyrics once and the credits once, with the times
           starting at zero, and save these two scripts as separate files.
           When your "main" script includes these other scripts, they will
           be incorporated properly into the main script to start at the
           proper time (which is <time> added to the first time event in
           the included script), and any overlapping time ranges will be
           interwoven properly.

           <time> is specified in the form H:MM:SS.FF, where H is an hours
           digit, M is a minutes digit, S is a seconds digit, and F is a
           fractional-second digit.  The units of F are determined by the
           #T command (below), and default to 30 units/second if the #T
           command was omitted (that is, the FF digits are SMPTE units
           ranging from 00 to 29).  The included script may in turn contain
           its own, possibly different, #T command, and also its own
           #I commands.  <time> always offsets the "includee" relative to
           the beginning of the "includer," taking into account the
           "includer's" own offset if the "includer" was itself included by
           some other script.

           <filename> may be any valid path + file name.  <filename> can
           specify a complete path; if no path is specified then JACOsub
           will look in the default scripts directory, which you can set in
           the General Config menu.  If you omit the extension in
           <filename>, then the program will include the script with the
           most recent time-stamp, among the extensions .js, .tts, .pjs, or
           .tim (.jsc, .pan, or .sub files won't be considered).  The file
           name must not contain any spaces.

           Any occurrences of #F, #P, #Q, and #R in an included script will
           be ignored.  These commands work only in the primary script, and
           they affect all included scripts.  The effects of #D, #S, and #T
           commands are passed down into included scripts, but these
           commands inside an included script affect only that script and
           others IT might include; they have no effect on the higher-up
           "calling" scripts.

           Example: #I 0:21:44.16 scripts:kor/kor-credits.js

   #P[ALETTE] <color> <r> <g> <b> [palette]
           This sets the red, green, and blue intensities for color
           register <color>, to <r>, <g>, and <b>, respectively.  This
           command may be specified anywhere in the file, but the setting
           will be used for the entire script.  Use intensities of 14 or 15
           with caution, as these are stronger than normal video signals,
           and can result in color bleeding when using in your genlocked
           video signal.  Do not redefine color 2; JACOsub expects it to
           remain black.

           The optional [palette] parameter defaults to 0, and indicates
           the palette number in which to set the color.  JACOsub has 10
           palettes available.  All 10 palettes are initialized to initial
           values set in the Playing / video Config menu.  Palettes 1 - 9
           may be used to reset temporarily certain colors for a particular
           display, using the CP directive.  If JACOsub is using a
           2-bitplane display, for example, you are restricted to 4 colors
           at any one time, but using multiple palettes allows you to
           redefine them on the fly.

           Examples:
           #P1 14 14 6    # set color 1 to yellow, in default palette 0
           #P1 d d 6      # same as above, using hexadecimal RGB values
           #p 3 0 13 0 1  # set color 3 to green, in palette 1

   #Q[UANTIZE] [n]
           This command has the effect of eliminating timing gaps between
           subtitles of less than [n] time units, as specified by the #T
           command.  Default is #Q0.  Example:  With #t30 and #q2
           specified, any time event less than 2/30 seconds earlier than
           another time event will be rounded up to the later event.  This
           is of questionable usefulness.  If this command occurs before a
           #T command, then 30 units per second is assumed.  Subsequent #Q
           commands replace earlier ones.  Only the last #Q command in a
           script has any effect.

   #R[AMP] <seconds.units>
           If you play a pre-timed script, and discover a time drift, then
           use this command.  The parameter <seconds.units> is the amount
           of drift to correct over the entire script.  Script timings will
           be adjusted appropriately according to this value.  A positive
           value will lengthen the total script running time, and a
           negative value will shorten the total script running time.  The
           default value is #R0.  The number after the decimal point is NOT
           a fractional second; it is the number of time units specified by
           #T.  THIS COMMAND MUST NOT OCCUR BEFORE A #T COMMAND.  Examples:

           #R-3.60  will shorten the script running time 3 seconds plus 60
                    time units.
           #R .92   will lengthen the script running time 92 time units.

           IMPORTANT:  Your genlock affects the computer's internal clock.
                       If you find that you have to ramp a 30-minute script
                       more than 10 seconds, then you have a bad problem
                       with your genlock.  DO NOT TRY TO "FIX" THE PROBLEM
                       WITH A BIGGER RAMP TIME!  Doing so will result in
                       math overflows, causing sudden jumps in timing.

   #S[HIFT] <[[hours:]minutes:]seconds.units>
           The parameter <seconds.units> is the amount to shift each time
           event in the script.  A positive value will delay each time, and
           a negative value will advance each time.  The default value is
           #S0.  The number after the decimal point is NOT a fractional
           second; it is the number of time units specified by #T.  THIS
           COMMAND MUST NOT OCCUR BEFORE A #T COMMAND.

           The first occurrence of #S in a script determines a global
           amount of shift, even if the first #S appears AFTER some timed
           lines.  Subsequent occurrences affect only those lines following
           the #S.  You must take care that your #S commands do not cause
           any times to be less than zero.  The Amiga uses unsigned
           integers (always positive) for its internal representation of
           times, meaning that a time "less than" zero is actually a very
           large number!

           Example:  #S -0.20 will cause ALL events to occur 20 time units
           sooner than usual, if this is the FIRST #S.  Otherwise, all
           events SUBSEQUENT to this command will be shifted so that they
           occur 20 units sooner.

   #T[IMERES] <n>
           Time resolution; sets time units to <n> per second.  The default
           is SMPTE units of 30 counts/second, as in #T30.  If your script
           is in units 1/100 second units or PAL units, you must say so
           with the appropriate command, before the subtitle text begins.
           The #R or #S commands cannot precede a #T command.

           Examples:  #t100
                      #TIMERES 25


3.  TIMED LINES
===============

Timed lines for the script may occur in any order.  They look similar to
this:

   H:MM:SS.FF H:MM:SS.FF directive {comment} text {comment} more text...

For example:

   0:30:57.22 0:30:59:46 vm {opening credit} A Film By Akira Kurosawa

Here's what all those pieces are:

Start time and stop time
------------------------
The first field is the time when the subtitle is to appear on the screen.
The normal default is SMPTE format (that is, FF can range from 00 to 29).
Use the #T command (described above) to define the units.  IMPORTANT: The
FF digits represent time units, NOT fractions of a second.  There is a
difference!  For example, if you use #T10 to specify 1/10 second time
units, then a time such as 0:00:00.60 would be illegal (and result in an
error) because it specifies 60 time units!  0:00:00.6 or 0:00:00.06 or
even 0:00:00.00006 would be correct for this case -- 6 UNITS are specified,
not 6 tenths of a second.

The second field is the time when the title is to disappear.

If you prefer, you do not have to use the H:MM:SS.FF format at all.
Instead, you can substitute a @ symbol followed by a single integer to
represent total time units.  For example, if #T30 is used to specify 1/30
second units, then the 0:05:10.22 is the same as @9322.  This format is
useful for representing times as video frame counts.  Many laserdisc
players display times in this fashion.

Directive string
----------------
The next field is the directive.  It is optional.  If you leave it out, the
program will default to standard subtitling form (all text centered at the
bottom of the screen or depending on how you have your global default
directive set in your configuration).  The title text MUST begin with a
non-alphabet character {such as a comment} if you omit the directive.
Directives are explained fully in the DIRECTIVES section below.  The first
non-whitespace character following  the directive is assumed to be the
beginning of the subtitle text.

Inline comments
---------------
The {comment} is considered a part of the subtitle text, but it is ignored
by the software.  Use it for character names or keywords.  A comment must
be enclosed in braces.  Comments may appear anywhere within the text of a
subtitle.  If you really want to to display a left brace, precede it with a
backslash like so: \{.  Right braces will be interpreted as a literal
character or close of a comment, whichever seems appropriate.  If a
whitespace character immediately follows a comment closing brace, then that
first whitespace character will be ignored.  Any other kind of following
character will be considered part of the subtitle text, and used.  Comments
in the text are especially useful when translating foreign films -- we use
them to list possible translations of phrases we are not yet sure about.

Title text
----------
In the example above, the "text" and "more text" fields are what get
displayed.  There are several special codes that you can put inside the
text (CASE IS IMPORTANT HERE ONLY):

Special character codes:

   \    Concatenate.  If the LAST character in a line is a backslash, then
        JACOsub will concatenate the text on the next line to the text
        in the current line.  Leading and trailing whitespace will be
        stripped from the concatenated text, so you can indent it if you
        wish.

   \n   Newline.  This is like a carriage return.  A line containing this
        code will be split at the \n.  Each of these new fragments will
        then be wordwrapped separately unless you turn wordwrapping off
        (see the W directive below).  \n is useful for general formatting.
        Multiple \n codes may be concatenated to create blank lines.
        Example:  Hello!\n\nHow are you?{blank line separating the two}

   \{   Display a left brace.  Left braces are normally used to indicate
        the beginning of a comment.

   \~   Display a tilde.  Tildes are normally used to create "hard" spaces
        (see below).

   \\   Display a backslash.  Backslashes are normally used to denote these
        special codes.

Insertions:

   \D   Insert current date into the title.  The date will be of the format
        DD MMM YYYY, as in 2 Apr 1996.

   \T   Insert current time into the title.  The time will appear as HH:MM
        (24-hour time).

Font codes:

   \N   Normal.  All text appearing after this code will be displayed in
        "normal" style.  This is typically the default, unless you have the
        style (S) directive set to something other than normal.  Note that
        this code is an uppercase \N -- a lowercase \n is a newline code.

   \I   Italics.  Display all text appearing after this code in italics.
        Example:  \IHello!\N\nHow are you?{Hello is in italics}

   \B   Boldface.  This one isn't particularly useful, but go ahead if you
        feel like it.  Text characters will be slightly fatter.

   \U   Underline.  This is virtually useless for large color text.

   \Cn  Color n.  The text following this code will be displayed using face
        color n.  n is a hexadecimal digit; it may take the values 0-9 or
        A-F (or a-f).  Typically, when using the font supplied with this
        software on a 2-bitplane display, only colors 3 and 1 are useful.
        See the CF directive below for some caveats about colors.

   \Fn  Font n.  The text following this code will be displayed using font
        number n.  n may range from 0 to 9 (or 0 to 3 if the program is
        not registered).  Normally you would use the F directive to set the
        default font for a line; use this escape code to override it.

THE FONT CODES ABOVE AFFECT ONLY ONE TIMING LINE; their effects do not
carry over into other lines.  These codes override any directives.  The \I,
\B, and \U codes are mutually exclusive:  You can have bold text or italic
text, but you cannot create text that is BOTH bold and italic.  See the 
demo script file (demo.js) for good examples on usage.

Leading or trailing space in subtitle text will be ignored.  If you want to
encode a true space on the ends of some text, use a tilde (~).  It will be
displayed as a space.  To actually display a tilde, precede it with a
backslash: \~.  Tildes may also be used to create "hard" spaces; they will
be displayed as spaces but text will not be wordwrapped on these spaces.

White space between line arguments may consist of any amount of spaces or
tabs.  Each tab character inside the subtitle text will be converted to a
space character.


4.  DIRECTIVES
==============

Directive strings were briefly described above, but there are so many that
they deserve to be allocated a whole section of this document.

A directive is a series of character codes strung together.  A directive
determines a subtitle's position, font, style, color, and so forth.  Each
character code begins with an alphabet character followed by arguments made
up of other alphabet characters and numbers.  Directives may contain any of
the following codes, in any order.  The directives may be uppercase or
lowercase.  Like the text codes above, directives only affect a SINGLE
timing line; their effects do not carry over into other lines.  Any
parameters shown here in square brackets [] are optional.

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

    VA     Continue this line directly Above the previous one.  This is
           the opposite behavior of VU below.  This is a useful directive
           for those cases where you want a new line to appear above the
           previous line's position, even if both lines do not share the
           same time range.  See VU below for more details.

    VB[n]  Bottom.  Position last line at the bottom (default).  The offset
           from the bottom of screen n is optional  - it says how many
           raster lines to offset from the physical bottom-of-viewport.  VB
           by itself is the same as VB16 (in the original default for this
           software).  The default value of n can be changed using #D
           command or in the General Configuration settings.

    VHn    Line height (i.e. spacing), where n is the percentage of the
           font height to use for line spacing.  Default is 100 (single-
           spaced).  Using 200 would result in double-spaced lines.  n may
           range from -32768 to 32767, although the useful range is
           probably more like 50 to 500.

    VL[n]  line n. Position subtitle starting at text line n (the height
           of a line depends on the font you use).  n=0 is the top line.
           If n is negative or omitted, the line will appear in the same
           vertical position as the preceding timed line.

    VM[n]  Middle.  Text will be centered vertically in the area defined by
           the VTn and VBn directives.  The optional parameter [n] is a
           positive or negative integer that will cause the centered block
           to be shifted up or down [n] lines (line height determined by
           the VH setting).

    VPn    Pixel n. Position subtitle so that the font baseline of the
           first line of text is n pixels from the top of the viewport.
           You need to know your font's baseline position for this
           directive to be of any use.  The mouse-positioning operation in
           the script editor creates directives like this.

    VS[n]  Scroll at speed n (default -2).  n<0 is number of frames to wait
           per raster line scrolled.  n>0 is number of raster lines to
           scroll per frame.  n may range from -6 to 4, with the values -1,
           0, and 1 all treated the same.  Text will scroll in from the
           bottom of the display and scroll off the top.  If the start time
           of scrolled text is the same as the end time of the previous
           view, the previous view will be scrolled off as the new text is
           scrolled in.  The new text to be scrolled in will begin at an
           offset below the bottom edge of the screen, controlled by the VT
           offset quantity.

           IMPORTANT CONSIDERATIONS:
           1.  Overlapping time ranges are ignored, except for
               concatenations caused by VU directives.  Use the VU
               directive to concatenate title paragraphs, otherwise use the
               end-of-line concatenation escape character (\).
           2.  Be sure you give the titles sufficient duration for the
               scrolling to complete -- if the duration is too short,
               scrolling will complete anyway, delaying anything scheduled
               to happen immediately afterward.
           3.  The only really useful scrolling speeds are -2 or less.
               Speeds of 2 or higher are almost too fast to read anything,
               and the maximum speed of 4 is usually too fast for the
               program to keep up with.  Speeds -1, 0, and 1 (all treated
               the same) result in strange distortions due to the fact that
               the video is interlaced.  This fact, combined with an odd-
               numbered scroll at every video refresh, causes only every
               other line in the bitmap to be visible during the scroll.
           4.  Regardless of whether the speed is even or odd, positive
               speeds that do not divide evenly into your screen height
               will be reduced to the next lower speed that does divide
               evenly.
           5.  The following directive prefixes will be ignored:  E, CS,
               FC, FD, FO, FS, FQ, I, and R.
           6.  Scrolling may not be smooth for large fonts or color fonts,
               or it may be smooth but the text may not be generated
               rapidly enough to keep up with the scroll.  Either way, the
               program will warn you if you try to scroll a color font.  It
               works best with small-to-medium sized mono-color fonts.
           7.  Under AmigaDOS 1.3 and below, fonts with slightly
               overlapping bitmaps may not be spaced properly.  The program
               will warn you of this if you try it under 1.3.
           8.  The VU directive may be used after VS to append more text.
               You should use VU to concatenate paragraphs of scrolling
               titles.  This is more memory-efficient than using the \
               concatenation code at the end of each line.
           9.  You can use embedded codes to change text style and color,
               but be careful changing fonts in the middle of a line.
               Changing fonts works best if the new font is on a separate
               line all its own, or if the new font is the same size as
               other fonts on the same line.
          10.  This directive uses a significant amount of display memory;
               equivalent to slightly more than two additional display
               buffers.  Insufficient RAM will cause scrolled titles to be
               skipped.  Sometimes the scrolling bitmap will fail to
               allocate from fragmentation in the available display memory.
               Shutting down the program and restarting it might alleviate
               this fragmentation enough to facilitate scrolling.

    VT[n]  Top.  Position the title with the first line at the top.  The
           offset n is optional - as with VB, VT by itself is the same as
           VT16 in the original distribution of this software.

    VU     Continue this line directly Underneath the previous one.  This
           is useful if you want a line with different directives grouped
           in the same vertical-positioning block as the previous line.
           It's like the line-concatenation escape code (\) only it doesn't
           continue the previous line where it left off, but instead starts
           a new line below it, positioning the previous line higher, if
           necessary, to make room for the new line.

           You can also use the VU directive to create interesting effects
           when a line with the VU directive does not share the same time
           range as the previous line.  For example, suppose you had a
           single line that used the VM directive.  Normally it would be
           perfectly centered vertically on the screen.  However, if a VU
           line follows it, both are positioned as if they were a single
           block of lines to be centered on the screen together; i.e. the
           VM line will appear slightly above center and the VU line will
           appear slightly below center, regardless of WHEN they are
           individually displayed.  Had VB been used instead of VM, the
           first line would have appeared raised one text line higher than
           bottom, just enough to make room for the second line.  VA has
           the same effect as VU if the lines are reverse-ordered in the
           script.

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

  Margins:

    HLn    Left margin.  Set left margin at a position that is n% of the
           the screen width.  Default is HL1 (1% from left edge).  Minimum
           value is -128 (way past the left edge of the display area).

    HRn    Right margin.  Set the right margin at a position that is n% of
           the screen width.  Default is HL99 (1% from right edge).  The
           right margin MUST be greater than the left margin.  Maximum
           value is 127, although anything greater than 100 is useless.

  Text justification:

    JC     Center.  Text is centered within H constraints (normal default).

    JF[:p] Full.  This aligns the left and right edges of text flush with
           the ends of the widest wordwrapped line in the text block.  If
           you want the justified text to span the full margin width, set
           wordwrapping to W2 (greedy) instead of W1 (smart, the default).
           The :p is a position parameter.  It may be :C (default), :L, :R,
           or :U, for Center, Left, Right, and Unconditional, respectively.
           :C, :L, and :R control the position of non-wordwrapped lines
           such as single short lines or the last line in a wordwrapped
           block -- these will not not be stretched to fit the block width.

           (Remember, \n codes delimit wordwrapped blocks; a title split
           by \n codes will wrap and justify each section as if they are
           completely separate titles.  If you want to justify a title
           properly, you should remove all \n codes except for where the
           wrapping and justifying should end.)

           The :U parameter means "unconditional."  JF:U is the same as JU.
           JF:U causes ALL lines in the block, wordwrapped or not,
           including the last line, to be stretched to fit exactly within
           the margins.  JF:U is useful for titling credits like this:

                  Clint Eastwood . . . . . . . Dirty Harry

           All the spaces will then be adjusted so that the line fits
           exactly inside the margins, and a list of these credits will
           have flush left and right edges.  You will need to experiment
           with the number of dots and spaces to get it all to look good.
           You can also try elminating the spaces between the dots, or
           substituting dashes, for somewhat different effects.

           JF[:p] commandeers one character in each proportional font for
           use as an adjustable space; the decimal character code used will
           be one of: 128, 31, or 127, whichever is available (hex codes
           80, 1F, or 7F, respectively).  The JF directive has no effect on
           fonts lacking all of these character codes.  Mono-spaced fonts
           are likewise unaffected.

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

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

    JU     Obsolote directive; identical to JF:U

  Block justification:

    JBC    Justify block center.  Because of wordwrapping, the width of a
           text block will never occupy the full width specified in your
           margin settings.  This directive positions the imaginary
           rectangle occupied by the text in the center of your margin
           settings, regardless of the text justification directives.  For
           example, the JL directive by itself might produce the following
           effect (the | character indicates margin boundaries):

           | The quick brown fox                      |
           | jumped over the lazy dog.                |

           but the JL directive together with JBC will preserve the text
           justification but center the block of text between the margins:

           |        The quick brown fox               |
           |        jumped over the lazy dog.         |

           AnimEigo video products have their subtitles displayed this way.

    JBF    Justify block full (default).  Text will be positioned according
           to whatever text justification directives are in effect, using
           the full width specified by the current margin settings.

    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.

  Wordwrapping:

    W0     Disable automatic wordwrapping.  This may result in your text
           not fitting within the position constraints defined with H & V.
           There is really NO reason at all why you would want to turn off
           wordwrapping; you can wrap words manually with the \n code
           whether wordwrapping is on or off.  This directive is here just
           for the sake of completeness.

    W1     Automatic "smart" wordwrapping (default).  Even if a your text
           contains newline codes, the separate substrings will be word-
           wrapped if necessary.  This wordwrap mode uses a "smart"
           algorithm that attempts to minimize the area of the screen
           occupied by the title.  In this mode, you will never see a line
           wrapped as shown (the | characters indicate margin boudaries):

           | The quick brown fox jumped over the lazy |
           |                   dog.                   |

           Instead, the W1 alghorithm will attempt to minimize the text
           area without using any extra lines, resulting in:

           |           The quick brown fox            |
           |        jumped over the lazy dog.         |

           This is easier for the viewer to read.  Same margins, same
           number of lines, but the lines are more equal in length.

    W2     Automatic "stupid" (generally known as "greedy") wordwrapping.
           If you are disconcerted by words not completely filling the
           horizontal margin space, and you don't mind having a single word
           hanging by itself on the last line (as in the first W1 example
           above), then use this directive.  This is the standard
           text-editor wordwrap algorithm, which makes no attempt at
           aesthetics.  Why anybody would want to use this is beyond me,
           but here it is.  \n codes behave the same as with W1.

Fonts
-----

  Font rendering:

    Fn     Use font n, where n is a number from 0 to 9 (JACOsub loads
           four fonts, which you can specify in the Config menu.  The usual
           default font is 0, which is what you should use as your
           "primary" font.  Fonts 4-9 are unavailable if the software is
           unregistered.

    FQ     Quick&Dirty text.  Text color 3 is always quick.  Other colors
           must normally be rendered one character at a time to avoid
           interference between the shadow and face color, but only when
           the font is designed with overlapping characters.  This
           interference happens because of a fault in the way the Amiga
           renders text.  The FQ directive forces all text on a line to be
           rendered in quick mode as if it were color 3.

           You should never need to use the FQ directive.  The program is
           smart enough to determine when a font can be quick&dirty.  For
           example, JACOsub's 32- and 36-pixel fonts will default to clean
           mode because they have overlapping characters, but the 32-pixel
           font will default to Quick&Dirty because its characters do not
           overlap.

    FC     Clean rendering.  Only color 3 will be rendered fast, other
           colors will be rendered so that the face color is not disturbed.
           You can use this directive to negate, on a single line, a global
           FQ directive set using the #D command.  Normally this directive
           will never be needed.

           The demo script demo.js tricks JACOsub into generating "slow"
           clean text in the foreground display so you can see how it is.
           If you are curious to see how the Amiga messes up color 1 text
           if it's displayed the quick way, run the demo after inserting
           the global command #DFQ at the top of the file demo.js before
           you play the demo.

    FD     Default text rendering.  Rendering will be "quick" or "clean"
           depending on how your font was set up in your configuration.
           This directive is useful for overriding a #DFC or #DFQ command.

    FBn    Blitter activity.  This overrides the "Use Blitter" program
           configuration setting.  If n=1, the blitter will be used to copy
           text between background video buffers for titles that extend
           over several time events.  If n=0, then time-overlapping text
           will be generated afresh on each video buffer.  Normally, the
           blitter should always be enabled.  However, blitting between
           buffers will also copy any imagery behind the title (like a
           graphic or shaded background), which might not share the same
           time range as the title.  If this happens, then disable the use
           of the blitter for that title with the FB0 directive.

    FOn[:a]  Generate an outline around the font, n pixels wide.  Color 2
           (JACOsub's outline color) is used to generate the outline.  This
           directive is useful for transforming a plain mono-color Amiga
           font into a nice titling font, especially when combined with the
           FS (font shadow) directive.  Recommended value for n is 2, which
           produces a nice flicker-free outline.  n must be less than 127.
           The maximum practical value is 3 or 4.  The default value is 0.

           The optional :a suffix indicates a color to use for anti-
           aliasing.  This defaults to the anti-alias setting in the
           Playing / video configuration, typically 2 (no antialiasing).

           WARNING:  Generating outlines can slow the program down
           considerably!  It is recommended that you use this directive
           only with QUICK&DIRTY font rendering, preferably with mono-color
           fonts.  An antialias color other than 2 will slow it down
           somewhat further.

    FSdn   Generate a font shadow, taking into account any existing font
           outline, in direction d, and n pixels deep.  Color 2 (JACOsub's
           shadow color) is used to generate the shadow.  The direction d
           is specified as a compass direction: N, S, E, W, NW, NE, SW, SE.
           Good values to use for the shadow depth n are 2 - 5.  The
           warning about font outlines above applies here also.

           Example: FSSE3 produces a shadow similar to the JACOsub 32-
           pixel font, with the shadow extending down and to the right.

  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 doesn't look good with colors
           other than color 3).

    SU     Underline (ugly!  Not recommended).

  Font color (CFn may also be set with text codes):

    CFn    Use color register n for the face color of the font.  JACOsub
           assumes that all color fonts use bitplane 0 (i.e. color 1) for
           the face color, and bitplane 1 (i.e. color 2) for the shadow/
           outline.  THIS IS IMPORTANT!  JACOsub will generate text
           differently depending on the color selected (see FF above).
           The foreground color may also be set using the \Cn code inside
           the text.

    CBn    Use color register n for the background color.  The display
           will be cleared to this color prior to building the text.  If
           two lines share the same display, and they have different
           background colors specified, the screen will be cleared using
           the latest NON-ZERO background color that occurs for that
           display.  In other words, non-zero colors override the default
           zero (transparent) background color.

    CPn    Use color palette n for this display.  Default value of n is 0,
           which is the primary color palette normally used by JACOsub.
           The values of n may range from 0 to 9, for a total of 10 color
           palettes.  All 10 palettes are initially set to a master palette
           which can be modified in the Playing / video Config menu, and
           they can be modified with the #Palette script command.

           Because the palette is loaded immediately following a video
           buffer switch, the new imagery on the display will appear with
           the old palette momentarily.  If this is too noticeable, then
           you should precede your alternate-palette lines with a "dummy"
           short-duration blank screen (containing a hard space) using your
           alternate palette, as in this example:

           0:00:12.20 0:00:12.22 cp2 ~{palette 2 on blank screen, .02 sec}
           0:00:12.22 0:00:14.50 cp2 This will appear with the new palette.

    CS[L]n[:s[:c]] This causes text to appear inside a shaded rectangle.
           The rectangle will be large enough to contain the text with a
           margin of n pixels on all sides.  The shading is user-defined
           (see the Playing / video Config menu) if s=0, or solid if s=1.
           Color c will be used for the rectangle.  The style (s) and color
           (c) paramters are optional; not setting them uses the defaults,
           normally s=0, c=2 (user-defined, black).

           Setting n=0 disables the shading.  We suggest using n=8 or more.
           Without the [L] parameter described below, only ONE shaded
           background rectangle will appear on the screen; that is, JACOsub
           will attempt to create a SINGLE box which contains ALL text that
           uses the CS directive and shares the same display.  If two
           shading directives for the same time range have conflicting
           parameters, one of the directives will be used, but predicting
           WHICH one is impossible.  The normal default setting is CS0:0:2,
           which can be changed using the #D command.

           The optional [L] parameter causes each text segment (which might
           be split by wordwrapping) to be shaded in its own rectangle.
           This looks ugly for a block of wordwrapped text, but it is
           useful for shading separate single lines that overlap in time.

           Notes:  Setting VB0 will mean that bottom-positioned text is as
           low as it will go, therefore shading cannot appear below it.
           You should set the VB directive so that there is room for the
           shading rectangle to extend below the text.  Also, VB text will
           be repositioned slightly higher when the running clock is
           displayed during play, but shade boxes will NOT be repositioned.

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

    GBn[Tm] Move the background slider control to n% saturation over a time
           period of m/60 seconds of time.  n may range from 0 to 100.  If
           time specifier is omitted, it defaults to 0 (i.e. instant).
           Zero saturation is a normal transparent background, allowing the
           video signal to show through all areas corresponding to color 0
           on the computer's display.
           Example:  GB63T120 slides the background fader to 63% saturation
           in 2 seconds (120/60 seconds).

    GGn[Tm] Move the graphics slider control to n% saturation over a time
           period of m/60 seconds of time.  100% saturation is the normal
           operating mode (full graphics), whereas 0% results in only the
           video signal with no overlaid computer graphics.

        >> DO NOT USE GG OR GB IN DEFUALT DIRECTIVES, or the genlock will
           be having control signals sent to it at every time event.

IFF graphic files (obsolete, see R directives)
-----------------
    IL     Same as RLB.  Retained for compatibility with previous versions.
    IS     Same as RLG.  Retained for compatibility with previous versions.

Special effects
---------------

Basic information and warnings:
1.  Only one effect can exist per time event.  If two titles share the same
    start time, but have different effects, only one effect will be
    executed for both titles.
2.  All these effects must be given sufficient time to complete.  Any
    time events that occur while the effect is in progress will be
    postponed until the effect is finished executing.
3.  With the exception of effects EN or E0, and ES, an effect directive
    will be ignored if the bitmaps for the current view and next view are
    incompatible (having different dimensions or depth).  This is not a
    problem for transitions between two normal video buffers; but the
    effect will be ignored if you try to transition to a graphic screen
    having different dimensions or display mode from the image currently
    displayed.
3.  In the descriptions below, the "d" parameter controls the direction of
    the effect, if applicable.
4.  The optional "[s]" parameter controls the speed of the effect, which
    may range from 1 to 64 (default is 8 if omitted).  The speed represents
    raster lines per vertical CRT blank.  If s=0 or s=?, the speed will be
    randomly chosen.
5.  If you notice "roughness" in the way these effects operate, try
    reducing either the effect speed or the number of colors you use for
    script playback.

    EBd[s] Blinds.  New view replaces old view as if Venetian blinds were
           opened.  Direction d may be V or H to specify vertical or
           horizontal blinds.

    ED[s]  Dissolve.  New view replaces current view by random memory
           replacement.  There are only three speeds: slow (s=0-9), medium
           (s=10-19), and faster (s>20).  This is probably not the best
           algorithm for a dissolve -- if anybody can write a better one,
           please send it to the author.  It needs to be cleaner and
           faster.  As it is, the only really useful speed is the maximum
           (s>20).  The actual speed will depend on your video buffer
           size (width, height, number of colors).

    EEVd[s] Reveal next view as if Eyelids open (d=O) or close (d=C)
           vertically over the current view.  This is actually two
           simultaneous vertical wipes in opposite directions on the top
           and bottom halves of the display.

    EEHd[s] This is a horizontal-wipe Eyelid effect.  It vaguely resembles
           the opening or closing of curtains.

    EId[s] Reveal next view as an Iris opening (d=O) or closing (d=C) over
           the current view.

    EN     Normal transition (default).  New view replaces old.  Also E0.

    EPn[:s] Palette fade.  Transform the current title palette to palette n
           in [:s] video fields.  This effect will be ignored if applied to
           a graphic file.  Speed may range from 0 to 255, instead of 1 to
           64, and the default speed is 32.

    EP+a[:b[:p]]
    EP-a[:b[:p]]
           Cycle forward (+) or backward (-) colors a through b (default b
           is the maximum color index) with a period of p video fields per
           cycle step (default 2).  This effect terminates at the next time
           event.  [:p] may be as high as 255.

    ERd[s] Smoothly Roll the current view off the display while rolling the
           next view in.  The direction d may be U, D, L, R (up, down,
           left, right).  Caveats:
           1.  This effect consumes much memory: the equivalent of two
               additional video buffers.  You may have to reduce your usual
               number of buffers or colors to make this effect work.
           2.  Horizontal rolls (left and right) are not possible under
               AmigaDOS 1.3.  They will be converted to up and down,
               respectively.

    ESd[s] Scroll new view up into the display if d=U, or reveal new view
           by scrolling current view down if d=D.  This directive will also
           work if the bitmaps are incompatible, i.e., if either view is an
           graphic view created by the RLG directive.  This is not a
           "smooth" scroll; you may not find it acceptable.

    EWd[s] Wipe next view over current view in the given direction d (U=up,
           D=down, L=left, R=right).

    E?[s]  Random transition chosen from those above, with random speed if
           [s] is also a question mark (?), or zero.  Ignored for
           incompatible bitmaps when applicable.  The Random effect does
           not include the Palette effects.

Argument directives (using the title string as parameter arguments)
-------------------

    DO NOT USE THE R DIRECTIVES IN A #D DIRECTIVE DEFINITION.

    RLB <ILBM file name> [<x offset %> <y offset %>]
           Load an IFF graphic file (typically a brush file) into a video
           buffer for the time interval specified by the start and stop
           time.  When this directive appears, JACOsub assumes that the
           remainder of the line is information about the file, NOT title
           text.  The file name must follow the directive string.  The
           position to display the image, specified as percent of screen
           width and height from the center, can be specified in the next
           two fields.  These position coordinates default to 0 0 if they
           are omitted, which results in the picture being centered on the
           screen.  The picture may be positioned to extend beyond the
           display edge.

           Any IFF graphic picture or brush may be specified.  As many as
           40 images may be loaded onto a single screen.  This enables you
           to create several small brushes and display them all at once, in
           different areas of the screen.

           CAVEATS (READ CAREFULLY!):
           1.  You need at least AmigaDOS 2.0 to use this directive.  Under
               1.3 and below, this directive is ignored unless you have a
               1.3-compatible version of iffparse.library in your libs:
               directory.
           2.  If a file is too big to fit in memory, the file will simply
               not load, and the program will beep to alert you.
           3.  If the graphic file contains more bitplanes than the JACOsub
               video buffers, the EXTRA BITPLANES WILL BE IGNORED.  You may
               change the number of JACOsub's bitplanes in the
               Playing / video Config menu.
               If you have JACOsub set for a 4-color (2-bitplane) screen,
               and you try to load in a 16-color (4-bitplane) picture, you
               will lose 2 biplanes of information, and the picture will
               look strange when it appears.
           4.  All pictures are treated as brushes.  Therefore, your
               picture, once loaded, will use JACOsub's color palette.  THE
               PICTURE'S OWN COLOR PALETTE WILL BE IGNORED.  Create your
               graphics using the SAME palette you use with JACOsub or the
               picture will look strange when it appears.  If you want to
               load a picture with its own colors, use the RLG directive
               (but then you won't be able to display text on top of it).
           5.  JACOsub attempts to load graphic files as they are needed.
               This can cause a slight video switch delay if a time event
               occurs while a file is loading, even though the graphic
               loading routines do check the clock frequently.  Keep your
               images on a fast hard disk, or better yet, in RAM:.  If you
               do not have sufficient memory, then do not use this
               directive!

    RLG <ILBM file name>
           Load an IFF graphic file into its own screen, with its own
           resolution and colors.  This screen will temporarily replace
           one of the video buffers.  As with RLB, JACOsub assumes that the
           text following the RLG directive contains the file name to load.
           JACOsub will attempt to center the picture on your screen.

           The RLB caveats 1, 2, and 5 above apply here also, and the RLG
           directive has some additional considerations:

           1.  You cannot display text on top of a picture loaded with
               the RLG directive.  Use the RLB directive for this.
           2.  The time ranges associated with a graphic screen should NOT
               overlap any other time ranges.  If they do, the start time
               for the graphic has priority over any unrealized end times.
           3.  The RLG directive can tax your memory even more severely
               than the RLB directive, especially if you load a pictures
               like hi-res HAM images to substitute every video buffer.
           4.  We observe difficulty loading Extra-Halfbrite pictures.
               Try it for yourself.  HAM and AGA images seem to work OK.

    RDB <LeftEdge> <TopEdge> <RightEdge> <BottomEdge>
           Draw a solid rectangle in the current text color with diagonal
           corners at the coordinates specified.  Coordinate units are
           percentages of the display width and height.  This is useful
           for making video letterbox margins really black.  To make the
           rectangle appear behind text, be sure it occurs in the script
           physically before the text, with a start time less than or equal
           to the text start time.

    RX <ARexx script name>
           Execute the ARexx script name that follows the RX directive.
           You should not specify other directives on the same line.  Only
           one RX directive may be specified per time event -- that is, if
           you have several lines all sharing the same start time, no more
           than one of them may contain an RX directive.  If more than one
           RX directive is specified for a given start time, the one that
           occurs latest in the script will be used.  The end time for the
           line is ignored, but should be larger than the start time to
           avoid a compiler warning.  Try to make the end time equal to the
           next nearest start time to avoid creating unnecessary video
           frames.

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

Because all of the above directives are optional, there is one other set of
directives that may be used when you do not wish to specify any:

    D or D0   Default.  To be used if no other directives are used.  You
           don't even need this directive at all, if your text begins with
           a non-alphabetic character (such as a {comment}, number, etc.).

           Specifying D (or nothing) will use the program's default
           settings.  The default directive for JACOsub is normally

           HL1HR99VH100VT16VB16JCJBFW1E0F0FDFB1FO0:2FSSE0SNCF3CB0CP0CS0:0:2

           which you can change in the file JACOsub.Config, or with a #D
           command at the top of your script.  Confused?  Here they are
           spaced out:

           HL1 HR99 VH100 VT16 VB16 JC JBF W1 E0
           F0 FD FB1 FO0:2 FSSE0 SN CF3 CB0 CP0 CS0:0:2

           The R directives and the Genlock directives should NEVER be
           specified globally, nor in JACOsub.Config.

    Dn     The directives D1 - D30 may be defined with the commands
           #D1 - #D30.  You can use these "default" directives as shorthand
           for more complex directives that you may need in many places.
           If you put two D directives in the same directive string, the
           latest one will be used, and any previous directives ignored.

   [name]  A name enclosed in square brackets may be substituted for any
           of the D directives.  You must have previously defined this
           name when you defined the D directive.

Other directives may be appended to a D directive to modify the behavior
of that D directive.  For example, if you defined a directive to use font
0 and color 1, and decided to name it "credits" then you would say:

   #D2 F0CF1 credits

Then, if you wanted to use the D2 (or "credits") directive with font 3
instead of font 0, you could modify the directive either of the following
two ways:

   0:00:12.01 0:00:19.20 D2F3        Leia performed Akira's voice.
or 0:00:12.01 0:00:19.20 [Credits]F3 Leia performed Akira's voice.

You can spell the directive name using uppercase or lowercase characters.

If a directive string contains conflicting information, the information
occurring last will be used.  For example, VTD will cause VT to be ignored
in favor of the default.  In the directive CF10JLCF3, CF10 will be ignored
in favor of CF3.  Naturally, any directive beginning with D is unaffected
by the D.  In the long default directive above, you can see VT16VB16.  This
serves to set the top-of-screen offset to 16 for later, and then sets the
default vertical positioning at 16 pixels from the bottom of the viewport.

Time track
----------

    Tx     Designate this line as belonging to track x, where x is any of
           the characters 0-9, A-F (case insensitive), or punctuation.
           This directive is ignored when compiling and playing scripts.
           All titles default to T0 if no track is specified.

The purpose of tracks is to let you assign unique designations to specific
title sequences interwoven with others in your script so that you can time
them separately.

For example, suppose you need to subtitle two people talking simultaneously
with music lyrics in the background.  This requires three independent
timing sequences.  There are two ways to do this:

1.  Separate blocks of titles.  Without using the T directive, you must
    arrange each sequence as a separate block of titles (remember, JACOsub
    doesn't care about order of the titles in your script file -- it will
    sort everything out according to start and stop times).

2.  One block of titles containing designated time tracks.  You can weave
    all the titles together as one long sequence, and designate separate
    tracks with the T directive so that the timing procedure can figure out
    which titles must be timed, and which must be skipped.

TRACKS WILL BE IGNORED IN ALL DEFAULT OR USER-DEFINED DIRECTIVES.
Furthermore, as far as JACOsub is concerned, trackes are not treated
internally as true directives at all.  Their only use is to flag lines for
the program's timing functions.


5.  SAMPLE LINES
================

These 4 lines all have the same effect.  Note that any spaces after the
directive and the first space after comments are ignored.

0:00:10.11 0:00:12.00 D  {fudo-ikiteru} It's alive!
0:00:10.11 0:00:12.00 D  {fudo-ikiteru}It's alive!
0:00:10.11 0:00:12.00 D  It's alive!{line doesn't start with a comment}
0:00:10.11 0:00:12.00    {fudo-ikiteru} It's alive!{starts with a comment}
0:00:10.11 0:00:12.00 [default] {fudo-ikiteru} It's alive!\
                      {this assumes the D directive was named to "default"}

If you want leading/trailing spaces, all of these lines will do the same
thing (put two spaces in front of and after the text):

0:00:10.11 0:00:12.00 D  ~~{fudo-ikiteru} It's alive! ~
0:00:10.11 0:00:12.00 D  {fudo-ikiteru}~~It's alive!~~
0:00:10.11 0:00:12.00 D  {fudo-ikiteru} ~~It's alive!~~
0:00:10.11 0:00:12.00 D ~ It's alive!~~
0:00:10.11 0:00:12.00 ~~{fudo-ikiteru} It's alive! ~
0:00:10.11 0:00:12.00  {fudo-ikiteru}~ It's alive!~~
0:00:10.11 0:00:12.00  {fudo-ikiteru} ~~It's alive!~~
0:00:10.11 0:00:12.00  {fudo-ikiteru}   It's alive!~~

THE FOLLOWING LINE IS BAD.  It needs either a directive after the timing
numbers, or a comment to indicate that subtitle text follows the timing
numbers.  Any alphabet character (A-Z, a-z) following the timing numbers
MUST be part of a directive.

0:00:10.11 0:00:12.00  It's alive!

For the next line, use color 1 for the font face color, start the
subtitle at the top of the screen and leave the other defaults alone,
and cause one word to be displayed in italics:

0:02:23.23 0:02:25.01 cf1vt {thug1-nani} Whaddaya \Imean\N, ``please?''

Note:  Normal quotation marks ("like this") may be used, but using a
double grave and a double apostrophe, as in the line above, looks more
professional on the screen.  Just make sure that the grave looks like an
upside-down apostrophe in your font, and that both characters occupy a
narrow space.  The JACOsub fonts are designed this way.

Additional note (THIS IS ONE OF THE BIG FEATURES OF JACOsub):
Timings may overlap!  The software will handle overlapping text displays
properly, but you must be sure to position your subtitles so that these
separate text events do not physically overlap on the screen.  You can
arrange timed lines in any order you want, separate overlapped events
into groups, or whatever.  The program will handle it.


6.  CREDITS
===========

The original JACOsub format was dreamed up by Alex Matulich and Daric
Koslowski, before any code was ever written for JACOsub.  Yes, this was the
second step!  (The first was to create the fonts.)  Beta testers and users
have been very helpful in expanding and improving the specification into
what it is today.  User feedback has played a large role in the development
of the software and the script format.  The entire JACOsub project has been
largely user-driven.

End of JScripts.doc.