1 files changed, 108 insertions, 0 deletions
diff --git a/man/man5/aewan.5 b/man/man5/aewan.5
new file mode 100644
index 0000000..d4d3cee
--- /dev/null
+++ b/man/man5/aewan.5
@@ -0,0 +1,108 @@
+.TH aewan "5" "August 2005" "aewan (Aewan Ascii Art Editor)"
+
+.SH NAME
+aewan \- File format documentation
+
+.SH 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 \fIzcat\fR or something of the sort. On a program, you will
+probably want to use the \fIzlib\fR 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.
+
+.SH 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.
+
+.nf
+<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
+.ff
+
+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.
+
+.SH 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.
+
+.SH 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).
+
+.SH 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.
+
+.SH 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.
+
+.SH SEE ALSO
+\fBaecat\fR(1), \fBaewan\fR(1)
+