Provided by: aewan_1.0.01-3_i386 bug

NAME

       aewan - File format documentation

INTRODUCTION

       Starting with version 0.9.0, Aewan features an all-new, easier to parse
       file format. Prior versions used a binary (largely  undocumented)  file
       format,  and  relied  on a program (ae2aes) to convert it to a readable
       format. With the new format, the ae2aes utility became unnecessary  and
       was deprecated.

       An  aewan  document is a gzipped file. Therefore, you must first gunzip
       it in order to be able to parse its contents. On the command line,  you
       could  use  zcat  or  something  of  the  sort.  On a program, you will
       probably want to use the zlib library.

       In the future it might be better for Aewan to supply a  shared  library
       to  enable  parsing  of aewan files with minimal effort. Such a library
       would have to be integrated with the editor in order  not  to  have  to
       duplicate  code  (i.e.  the editor itself would be just a client of the
       library).  But for the time being, you  have  to  read  and  parse  the
       format on your own.

FILE FORMAT

       In  the  description  below,  the  items  in  between  brackets are NOT
       literal, they are placeholders. [S] is a placeholder for a  string  and
       [N]  is  a  placeholder for a decimal integer, and [B] is a placeholder
       for a boolean value ('true' or 'false').  A  line  with  "..."  is  not
       literal  either,  it  just  means that the lines above repeat a certain
       number of times.

       <Aewan Document v1
          layer-count: int: [N]
          meta-info: str: [S]
          <Layer
               name: str: [S]
               width: int: [N]
               height: int: [N]
               visible: bool: [B]
               transparent: bool: [B]
               layer-line: str: [S]
               layer-line: str: [S]
               layer-line: str: [S]
               (...there are <height> such lines...)
          >Layer
          (...there are <layer-count> such blocks...)
       >Aewan Document v1

       Indentation is ignored, but all other whitespace is significant.
       In particular, you can't omit the space that immediately follows
       the ':' field delimiters, or supply more than one space there.
       Notice that the file format does not use any quotation marks
       for the values, not even strings.

REPRESENTATION OF STRINGS

       Strings are represented almost literally in the  file  (where  the  [S]
       placeholders  are  in  the blueprint above), and are not put in between
       quotes or anything. However, special characters (ASCII codes 1  to  31)
       are  escaped: the escape code is a backslash, followed by the character
       '0' + ch, where ch is the special character. Thus, a newline  character
       would be represented by "\:", since ":" is '0' + 10.

REPRESENTATION OF INTEGERS AND BOOLEANS

       Integers  use  just  the plain old decimal representation. The booleans
       are represented as strings: either "true" or "false" (without quotes).

REPRESENTATION OF LAYER LINES

       Each layer-line is a string, but it is specially formatted in order  to
       convey  the  characters  and  attibutes  in  that  line.  In  order  to
       understand the format of a layer-line string, it is first necessary  to
       introduce the concept of cells. A cell in an aewan layer is each of the
       spaces that can contain a character. A cell has two pieces of data: the
       character  that is in it, and a color attribute.  The character is just
       that: an 8-bit value represing the character  drawn  there.  The  color
       attribute  is  an  8-bit  unsigned  value that packs the foreground and
       background color of a  given  cell,  as  well  as  standout  and  blink
       attributes.

       The  following color codes are used: 0=black, 1=red, 2=green, 3=yellow,
       4=blue, 5=magenta, 6=cyan, 7=white.

       The 8 bits of the attribute  have  the  following  meanings:  SFFFLBBB.
       Where  S  is  the  standout  bit,  FFF  is the 3-bit color code for the
       foreground color, L is the blink bit, and BBB is the 3-bit  color  code
       for the background color.

       The  layer-line string is composed of the hexadecimal representation of
       layer_width*2 bytes. Each 2 bytes is the information for  one  cell  of
       the  line:  the  first  byte  is  the  character, and the second is the
       attribute. For example, the hex representation for 'A' is  0x41,  so  a
       line  with  five 'A's each of them in a different foreground color (but
       all    with    black    background)    would    be    represented    as
       41104120413041404150.

LICENSE INFORMATION

       Copyright  (c)  2004-2005  Bruno  Takahashi  C. de Oliveira. All rights
       reserved.

       This program is licensed under the GNU General Public License,  version
       2  or, at your option, any later version. For full license information,
       please refer to the COPYING file that accompanies the program.

SEE ALSO

       aecat(1), aewan(1)