summaryrefslogtreecommitdiff
path: root/legacy/eet/doc
diff options
context:
space:
mode:
authorVincent Torri <vincent.torri@gmail.com>2008-10-16 08:41:40 +0000
committerVincent Torri <vincent.torri@gmail.com>2008-10-16 08:41:40 +0000
commit3e4465c4fac433a17bd93da7df2a6b4d5e4b26df (patch)
tree375048807db7bed4ddf33e55604c3c70226d7527 /legacy/eet/doc
parenta3f8f5f27b34f658950da3be95aea9bf93a59d8b (diff)
* add m4 macro for documentation, unit tests and coverage
* put documentation related files in doc, remove gendoc and add a doc rule to create the documentation and a doc tarball named eet-doc-$(version).tar.bz2 * minor cleanup in the autotools SVN revision: 36706
Diffstat (limited to 'legacy/eet/doc')
-rw-r--r--legacy/eet/doc/Doxyfile4
-rw-r--r--legacy/eet/doc/Makefile.am56
-rw-r--r--legacy/eet/doc/eet.c.in188
3 files changed, 211 insertions, 37 deletions
diff --git a/legacy/eet/doc/Doxyfile b/legacy/eet/doc/Doxyfile
index b553e4c31f..941fdea839 100644
--- a/legacy/eet/doc/Doxyfile
+++ b/legacy/eet/doc/Doxyfile
@@ -1,7 +1,7 @@
1PROJECT_NAME = Eet 1PROJECT_NAME = Eet
2PROJECT_NUMBER = 2PROJECT_NUMBER =
3OUTPUT_DIRECTORY = . 3OUTPUT_DIRECTORY = .
4INPUT = ../eet.c ../src/lib 4INPUT = eet.c ../src/lib
5IMAGE_PATH = img 5IMAGE_PATH = img
6OUTPUT_LANGUAGE = English 6OUTPUT_LANGUAGE = English
7GENERATE_HTML = YES 7GENERATE_HTML = YES
@@ -102,7 +102,7 @@ GENERATE_MAN = YES
102MAN_OUTPUT = man 102MAN_OUTPUT = man
103MAN_EXTENSION = .3 103MAN_EXTENSION = .3
104MAN_LINKS = YES 104MAN_LINKS = YES
105GENERATE_XML = YES 105GENERATE_XML = NO
106XML_SCHEMA = 106XML_SCHEMA =
107XML_DTD = 107XML_DTD =
108GENERATE_AUTOGEN_DEF = NO 108GENERATE_AUTOGEN_DEF = NO
diff --git a/legacy/eet/doc/Makefile.am b/legacy/eet/doc/Makefile.am
index 57448493e0..346819a4bc 100644
--- a/legacy/eet/doc/Makefile.am
+++ b/legacy/eet/doc/Makefile.am
@@ -1,46 +1,32 @@
1 1
2if BUILD_DOCS 2MAINTAINERCLEANFILES = Makefile.in eet.c
3
4# install documentation
5docdir = $(datadir)/$(PACKAGE)/doc
6
7all-local: doc-build.stamp
8
9# rule to remove all old created files
10doc-prepare.stamp:
11 @if test -d html ; then \
12 rm -rf html/ latex/ man/ xml/; \
13 fi
14
15# rule to build documentation and copy necessary files
16doc-build.stamp: doc-prepare.stamp
17 @doxygen
18 @cp img/*.png html/
19 3
20# rules to clean 4.PHONY: doc
21clean-local:
22 @rm -rf html/ latex/ man/ xml/
23 5
24# rule to install the documentation in $(docdir) 6if EFL_BUILD_DOC
25install-data-local:
26 @if ! test -d "$(DESTDIR)$(datadir)/$(PACKAGE)"; then \
27 $(mkinstalldirs) "$(DESTDIR)$(datadir)/$(PACKAGE)"; \
28 fi
29 @if ! test -d "$(DESTDIR)$(docdir)"; then \
30 $(mkinstalldirs) "$(DESTDIR)$(docdir)"; \
31 fi
32 @cp -pr html/ man/ latex/ xml/ "$(DESTDIR)$(docdir)"
33 7
34# rule to uninstall the documentation 8doc-clean:
35uninstall-local: 9 rm -rf html/ latex/ man/ xml/ $(PACKAGE_TARNAME)-$(PACKAGE_VERSION).tar*
36 rm -rf $(DESTDIR)$(docdir)
37 10
11doc: all doc-clean
12 $(DOXYGEN)
13 cp img/*.png html/
14 rm -rf $(PACKAGE_TARNAME)-doc-$(PACKAGE_VERSION).tar*
15 mkdir -p $(PACKAGE_TARNAME)-doc-$(PACKAGE_VERSION)/doc
16 cp -R html/ latex/ man/ $(PACKAGE_TARNAME)-doc-$(PACKAGE_VERSION)/doc
17 tar cf $(PACKAGE_TARNAME)-doc-$(PACKAGE_VERSION).tar $(PACKAGE_TARNAME)-doc-$(PACKAGE_VERSION)
18 bzip2 -9 $(PACKAGE_TARNAME)-doc-$(PACKAGE_VERSION).tar
19 rm -rf $(PACKAGE_TARNAME)-doc-$(PACKAGE_VERSION)
20 mv $(PACKAGE_TARNAME)-doc-$(PACKAGE_VERSION).tar.bz2 $(top_srcdir)
38 21
39MAINTAINERCLEANFILES = Makefile.in eet.c 22else
40 23
41DISTCLEANFILES = Makefile.in eet.c 24doc:
25 @echo "Documentation not built. Run ./configure --help"
42 26
43endif 27endif
44 28
45EXTRA_DIST = Doxyfile eet.css foot.html head.html img/ 29clean-local: doc-clean
30
31EXTRA_DIST = Doxyfile eet.css foot.html head.html img/ eet.c.in
46 32
diff --git a/legacy/eet/doc/eet.c.in b/legacy/eet/doc/eet.c.in
new file mode 100644
index 0000000000..3d6c02664b
--- /dev/null
+++ b/legacy/eet/doc/eet.c.in
@@ -0,0 +1,188 @@
1/**
2@file eet.c
3@brief Eet Data Handling Library Public API Calls
4
5These routines are used for Eet Library interaction
6*/
7
8/**
9
10@mainpage Eet Library Documentation
11@image html eet.png
12@version @PACKAGE_VERSION@
13@author Carsten Haitzler <raster\@rasterman.com>
14@date 2000-2008
15
16
17
18
19
20@section intro What is Eet?
21
22It is a tiny library designed to write an arbitary set of chunks of data
23to a file and optionally compress each chunk (very much like a zip file)
24and allow fast random-access reading of the file later on. It does not
25do zip as a zip itself has more complexity than is needed, and it was much
26simpler to impliment this once here.
27
28Eet is extremely fast, small and simple. Eet files can be very small and
29highly compressed, making them very optimal for just sending across the
30internet without having to archive, compress or decompress and install them.
31They allow for lightning-fast random-acess reads once created, making them
32perfect for storing data that is written once (or rarely) and read many
33times, but the program does not want to have to read it all in at once.
34
35It also can encode and decode data structures in memory, as well as image
36data for saving to Eet files or sending across the network to other
37machines, or just writing to arbitary files on the system. All data is
38encoded in a platform independant way and can be written and read by any
39architecture.
40
41
42
43
44
45@section example A simple example on using Eet
46
47Here is a simple example on how to use Eet to save a series of strings to a
48file and load them again. The advantage of using Eet over just fprintf() and
49fscanf() is that not only can these entries be strings, they need no special
50parsing to handle delimiter characters or escaping, they can be binary data,
51image data, data structures containing integers, strings, other data
52structures, linked lists and much more, without the programmer having to
53worry about parsing, and best of all, Eet is very fast.
54
55@code
56#include <Eet.h>
57
58int
59main(int argc, char **argv)
60{
61 Eet_File *ef;
62 int i;
63 char buf[32];
64 char *ret;
65 int size;
66 char **entries =
67 {
68 "Entry 1",
69 "Big text string here compared to others",
70 "Eet is cool"
71 };
72
73 eet_init();
74
75 // blindly open an file for output and write strings with their NUL char
76 ef = eet_open("test.eet", EET_FILE_MODE_WRITE);
77 eet_write(ef, "Entry 1", entries[0], strlen(entries[0]) + 1, 0);
78 eet_write(ef, "Entry 2", entries[1], strlen(entries[1]) + 1, 1);
79 eet_write(ef, "Entry 3", entries[2], strlen(entries[2]) + 1, 0);
80 eet_close(ef);
81
82 // open the file again and blindly get the entries we wrote
83 ef = eet_open("test.eet", EET_FILE_MODE_READ);
84 ret = eet_read(ef, "Entry 1", &size);
85 printf("%s\n", ret);
86 ret = eet_read(ef, "Entry 2", &size);
87 printf("%s\n", ret);
88 ret = eet_read(ef, "Entry 3", &size);
89 printf("%s\n", ret);
90 eet_close(ef);
91
92 eet_shutdown();
93}
94@endcode
95
96
97
98
99
100@section format What does an Eet file look like?
101
102The file format is very simple. There is a directory block at the start of
103the file listing entries and offsets into the file where they are stored,
104their sizes, compression flags etc. followed by all the entry data strung one
105element after the other.
106
107All Eet files start with t a 4 byte magic number. It is written using network
108byte-order (big endian, or from most significant byte first to least
109significant byte last) and is 0x1ee7ff00 (or byte by byte 0:1e 1:e7 2:ff
1103:00). The next 4 bytes are an integer (in big endian notation) indicating
111how many entries are stored in the Eet file. 0 indicates it is empty. This is
112a signed integer and thus values less than 0 are invalid, limiting the number
113of entries in an Eet file to 0x7fffffff entries at most. The next 4 bytes is
114the size of the directory table, in bytes, encoded in big-endian format. This
115is a signed integer and cannot be less than 0.
116
117The directory table for the file follows immediately, with a continuous list
118of all entries in the Eet file, their offset in the file etc. The order of
119these entries is not important, but convention would have them be from first
120to last entry in the file. Each directory entry consiste of 5 integers, one
121after the other, each stored as a signed, big endian integer. The first is
122the offset in the file that the data for this entry is stored at (based from
123the very start of the file, not relative to the end of the directory block).
124The second integer holds flags for the entry. currently only the least
125significant bit (bit 0) holds any useful information, and it is set to 1 if
126the entry is compressed using zlib compression calls, or 0 if it is not
127compressed. The next integer is the size of the entry in bytes stored in the
128file. The next integer is the size of the data when decompressed (if it was
129compressed) in bytes. This may be the same as the previous integer if the
130entry was not compressed. The final integer is the number of bytes used by
131the string identifier for the entry, without the NUL byte terminator, which
132is not stored. The next series of bytes is the string name of the entry, with
133the number of bytes being the same as specified in the last integer above.
134This list of entries continues until there are no more entries left to list.
135To read an entry from an Eet file, simply find the appropriate entry in the
136directory table, find it's offset and size, and read it into memory. If it is
137compressed, decompress it using zlib and then use that data.
138
139Here is a data map of an Eet file. All integers are encoded using big-endian
140notation (most significant byte first) and are signed. There is no alignment
141of data, so all data types follow immediately on, one after the other. All
142compressed data is compressed using the zlib compress2() function, and
143decompressed using the zlib uncompress() function. Please see zlib
144documentation for more information as to the encoding of compressed data.
145
146@verbatim
147HEADER:
148[INT] Magic number (0x1ee7ff00)
149[INT] Number of entries in the directory table
150[INT] The size of the directory table, in bytes
151
152DIRECTORY TABLE ENTRIES (as many as specified in the header):
153[INT] Offest from file start at which entry is stored (in bytes)
154[INT] Entry flags (1 = compressed, 0 = not compressed)
155[INT] Size of data chunk in file (in bytes)
156[INT] Size of the data chunk once decompressed (or the same as above, if not)
157[INT] The length of the string itendifier, in bytes, without NUL terminator
158[STR] Series of bytes for the string identifier, no NUL terminator
159... more directory entries
160
161DATA STORED, ONE AFTER ANOTHER:
162[DAT] DATA ENTRY 1...
163[DAT] DATA ENTRY 2...
164[DAT] DATA ENTRY 3...
165... more data chunks
166@endverbatim
167
168The contents of each entry in an Eet file has no defined format as such. It
169is an opaque chunk of data, that is up to the application to deocde, unless
170it is an image, ecoded by Eet, or a data structure encoded by Eet. The data
171itself for these entries can be encoded and decoded by Eet with extra helper
172functions in Eet. eet_data_image_read() and eet_data_image_write() are used
173to handle reading and writing image data from a known Eet file entry name.
174eet_data_read() and eet_data_write() are used to decode and encode program
175data structures from an Eet file, making the loading and saving of program
176information stored in data structures a simple 1 function call process.
177
178Please see src/lib/eet_data.c for information on the format of these
179specially encoded data entries in an Eet file (for now).
180
181
182
183
184
185@todo Add hash table, fixed and variable array encode/decode support.
186@todo Document data format for images and data structures.
187
188*/