# RAW plugin version 0.0.1
# Copyright (C) 1999 Jaroslav Benkovsky, <benkovsk@pha.pvt.cz>
# Distributed under GPL. See file COPYING for details.
#
# RCS: $Header: /home/benkovsk/worx/RAW/RCS/FORMAT,v 1.1 1999/01/31 22:39:33 benkovsk Exp benkovsk $


USER SPECIFIED FILE FORMAT V1.0 SYNTAX
======================================

This file describes syntax of file containing file format description
(i.e. it describes file format's file format :-). The format described
here is currently used version. It's probable that it will be massively
modified, revised and maybe dropped at all. I play with an idea to
rewrite it to LISP code - so it could be easily loaded and interpreted.

In the following text I use term 'format' mostly for the resulting
structure, describing raw file and it's associated load/save plugin.

Term 'syntax' is used for syntax of the file which describes 'format'
in the meaning mentioned in the previous paragraph.

'subplugin' is an interface of the RAW plugin which is specialized
for one particular format. This format can be used either indirectly
by selecting in the main plugin, or directly through the subplugin.


Table of Contents
=================
1.0 - Execution
2.0 - Format overview
  2.1 - Syntax
    2.1.1 - Field types
    2.1.2 - Directives


1.0 Execution
=============
Each available and valid format is read in whole into RAW plugin's memory 
first during GIMP startup (when querying for plugins) and second upon plugin 
invocation during file save or load. In these cases the directives from the
format are stored in memory and 'info' directives are used to register
subplugin for this format.

Only selected format is then evaluated - i.e. its' directives are processed.

2.0 Format overview
===================
With the exception of identification string there's no particular order
which has to be obeyed. Assignement directives ('ask', 'set' and 'hdr')
of the same type are processed in the order in which they are specified
('set' is a bit special). The other directives have more "proclamative"
character and might be specified in any order. However it's better
to stick to some order convention; that is used here.

2.1 Syntax
----------
Blank lines and lines beginning with hash ('#') or semicolon (';') are ignored.

Other lines are called "directives". Each directive can span only one line
now. Directives consist of fields.

Fields in the directives are delimited with colon (':').
Fields can be of several types: context, directive name, quoted string, 
number, variable reference, numeric constants and LISP expression.


2.1.1 Field types
-----------------
context
    determines if directive is valid for save or load. The context
    must be either unquoted word 'save' or 'load'. If left out, the directive
    is valid for both save and load.

directive name
    determines the meaning of directive. It is one word without quotes.
    The examples of directives are 'ask', 'header_fn', ...
    The directives are explained below.

quoted string
    is used for expressing string values. It is normal C-like string and
    can contain escapes and embedded zeroes. Not all C escapes are recognized
    - only \t, \n, \r, \", \\, \xNN and \NNN. It is automagically ended w/
    zero (\0). [ FIXME: really? ]

    Example:
      "Temporary\tstring\x0A"

number
    is used for expressing numeric values. It can be in any radix recognized
    by strtol() or strtod() and can have optional plus or minus sign.
    Although float is recognized, it is poorly implemented in other places
    in the code.

    Example:
      0x2300
      -20
      0.75

variable reference
    depending on context, it is used either as a string or numeric value, 
    or as a lvalue - i.e. target for assignment. It is written as a
    variable name. As it is used in Guile and PDB, it should have 
    reasonably sane name - one word, first letter, etc .... like identifiers
    in C.

    Example:
      alpha

numeric constant
    is used for specifying value for list types - like input field appearance,
    etc. These are similar to variable references, but the difference is that
    they are hardwired in the parser now. They are used exclusively as
    numbers and can be replaced with them.

    Example:
      TOGGLE

lisp expression
    is used as a string or numeric value. It always must have surrounding
    parentheses to be recognized as Lisp! The parser is rather simple now,
    so it can be easily fooled if the expression contains strings. It is
    beter to use simple expressions now.

    Lisp expressions are interpreted w/ Guile.

    Example:
      (* alpha 10)


2.1.2 Directives
----------------
[ FIXME ]

; RAW-Format Spec File v1.0
    It's identification of the format file. It must be always present on the
    first line in the file, else the file is not recognized to contain RAW 
    file format.

id:<string>
    Format identification. id is used to construct subformat plugin's name
    for PDB (RAW plugin name + "_" + id). 

    Parameter to the directive is the id. It should not contain spaces
    or other weird symbols as it will be used in PDB.

    Example:
      id:"colorcube"

name:<string>
    Name of the format, should be descriptive a bit. It's used in format 
    selection dialog and for constructing subformat plugin's blurb
    in PDB.

    Parameter to this directive is format name.

    Example:
      name:"colorcube format"

desc:<string>
    Verbose description of the format. It is only used for PDB description
    field now.

    Parameter to this directive is format description.

    Example:
      desc:"Demonstration format w/ colorcube and magic"

date:<string>
    Date of format's last modification. It is only used for PDB date field now.

    Parameter to this directive is format's last modification date.

    Example:
      date:"September 1998"

author:<string>
    Author of the format file. It is only used for PDB author field now.

    Parameter to this directive is format author.

    Example:
      author:"John Doe"

maintainer:<string>
    Maintainer of the format file. It is only used for PDB maintainer field 
    now. [ FIXME: isn't it a 'copyright' field? ]

    Parameter to this directive is format maintainer.

    Example:
      maintainer:"John Doe <doe@somewhere.org>"

loadmenu:<string>
    Menu path where the reference to the subformat load plugin will be placed.
    It's used for PDB menu field.

    Parameter to this directive is a menu path. It's usually in the form
    <Load>/short-name. Although I like to use submenus, they do not work 
    quite well in the Save/Load menus.

    Example:
      loadmenu:"<Load>/RawX/ColorCube"

savemenu:<string>
    Menu path where the reference to the subformat save plugin will be placed.
    It's used for PDB menu field.

    Parameter to this directive is a menu path. It's usually in the form
    <Save>/short-name. Although I like to use submenus, they do not work
    quite well in the Save/Load menus.

    Example:
      savemenu:"<Save>/RawX/ColorCube"

magic:<string>:<string>
    Defines file format magic for PDB. Unfortunately, many RAW formats do
    not have anything suitable for this, because their image files do not 
    contain file header or identification.

    First parameter to this directive is format file extension, e.g. "raw". 
    The second parameter is actual file magic, as used in /etc/magic
    file, or more appropriately, in gimp_register_magic_load_handler ().
    
    Example:
      magic:"raw":"0,string,COLORCUBE"

headersize:<numeric expression>
    Determines file header size in bytes. If the size is 0 (i.e. there's no 
    header), this directive can be safely omitted.

    Parameter to this directive is numerical expression. It should be
    noted, however, that its' value should not be based on parameters
    which are unknown before header is already read during image load.
    Thence, it's wise to keep it constant now.

    Example:
      headersize:32

type:<string>
    [ FIXME: what's it good for now? ]

[<context>:]set:<variable>:<expression>:<num constant>
    This directive assigns the value of the expression to the variable
    specified. The assignment is done during the specified phase of the 
    image saving/loading. [ FIXME: is expr. evaluated too? ]

    If context is specified, this directive is used only during the action
    the context specifies. Context can be save or load.

    The first parameter specifies the name of the variable assigned into.

    The second parameter specifies expression assigned.

    The third parameter specifies the phase during which the assignment
    is done. During each phase, all previously unprocessed assignements
    with phase numbers less or equal current phase are processed.

    Currently implemented is only phase PHASE_BEFHDR (30) - before header 
    creation/loading - and PHASE_DEFAULT (0) - default - which is 30 too :).

    Examples:
      set:majjic:"COLORFORM":0
      set:size:(* width height):PHASE_BEFHDR

[<context>:]ask:<variable>:<string>:<string>:<num constant>:<expression>[:<constraint>:...]
    This directive causes that during format subplugin's interactive invocation
    user is prompted for value of this variable. In case of noniteractive 
    invocation this will be passed as a plugin parameter.

    If context is specified, this directive is used only during the action
    the context specifies. Context can be save or load.

    The first parameter specifies the name of the variable prompted. It is used
    in Guile, so usual requirements for variable names in guile should apply.

    The second parameter is label string, used in dialog box for this variable.

    The third parameter is description string, used for tooltips and PDB
    (not implemented yet).

    The fourth parameter is input field type. It van be ENTRY, TOGGLE or SCALE.
    In future there should be LIST too. This value determines appearance of the
    field in dialog box. The SCALE is not completely implemented too.

    The fifth parameter is default variable value. It determines parameter type
    too.

    The sixth and others are optional constraint values. These are not 
    implemented yet, but in the future they will determine min and max value
    (for ENTRY or SCALE) or list items (for LIST).

    Example:
      load:ask:width:"Width":"Width of the image":ENTRY:256

[<context>:]hdr:<numeric expression>:<numeric expression>:<constant>:<expression>
    This directive describes the data to be stuffed into file header during
    image saving, or the data to be extracted/compared during image loading.

    The usual contents for image file header are magic string, image width 
    and height, color depth, color mode, number of frames, etc.

    During save this information is simply copied into the header. When 
    loading, two cases are distinguished: if field value is specified
    as a variable, this variable is filled with value from the header.
    This can be subsequently used for reconstructing proper image look.
    If field value is specified as a constant, the value in the header and
    the constant are compared. If they differ, warning is issued, as this
    this probably signifies inappropriate format (or poorly written one :-).

    If context is specified, this directive is used only during the action
    the context specifies. Context can be save or load.

    The first parameter specifies offset (in bytes, starting w/ zero) in
    file header, where the value is stored.

    The second parameter specifies size (in bytes) that the value occupies
    in the header.

    The third parameter determines the storage type of the value. Currently,
    it can be L, B, or S (or LITTLE, BIGEND and STRING). L and B mean 
    little-endian and big-endian integers.
    (little-endian means that least significant byte is stored on the lowest
    address, the most significant byte of the value is stored on the highest
    address. Big-endian means the very opposite). S means string [ FIXME:
    zero terminated? ].

    The fourth parameter is the actual value. For details see above.
    If the value is LISP expression, however, only save works fully.

    Examples:
      hdr:0x0000:9:S:"COLORFORM"
      hdr:0x000A:2:L:colorcube
      save:hdr:0x000C:2:L:(- bpp alpha)


header_fn:<string>
    Determines the function used for loading and saving the image header.
    Only "basic" is now implemented

    Parameter to this directive is identifier of the function in header-
    -functions table (see file header.c).

    Example:
      header_fn:"basic"

pixel_fn:<string>
    Determines the function used for pixels' translation beteween internal
    (gimp) and external (file) representations. For example, rgbacube
    function translates pixels from RGB(A) format used in GIMP to
    format based on user specified color-cube and vice versa.

    Parameter to this directive is identifier of the function in pixel-
    -functions table (see file data.c).

    Example:
      pixel_fn:"rgbacube"

drawable_fn:<string>
    Determines the function used for loading and saving the image drawable.
    For example, the function can save the drawable left-to-right, 
    upside-down (as is most usual) or upside-down, right-to-left
    (which is probably _not_ so common).

    Parameter to this directive is identifier of the function in drawable-
    -functions table (see file data.c).

    Example:
      drawable_fn:"lrud"

image_fn:<string>
    Determines the function used for loading and saving the image.
    For example, the function can save all drawables top-to-bottom
    or the opposite direction.

    Parameter to this directive is identifier of the function in image-
    -functions table (see file data.c).

    Example:
      image_fn:"single"
