Annotation of /psiconv/trunk/README

INTRODUCTION
============

This package is meant to make the Psion 5 series of PDAs, as well as other
small computers running EPOC 32, more usable to non-Windows users. But even
they may profit from the data I collected.

The package consists of several parts:
  * Documentation about Psion 5 data formats;
  * A library which can be linked against application that have to read
    and write Psion 5 files;
  * An example command-line program which reads Psion files and writes
    more commonly used formats.


DATA FORMATS
============

As far as I know, and have gathered from the newsgroups, Psion does not want
or is not able to release the data formats of the saved files of their
internal applications. I am trying to reverse engineer these data formats
and to document them for general use. At this moment, I understand their 
Word, Sheet, TextEd, Sketch, MBM, Clipart and Record files, as well as a 
few other less important formats. I want this information to be available
to everyone, in order to write better file conversion utilities for popular
(non-)Windows programs.

All documentation is written in Psion 5 Word. Fortunately, the utilities
in this package can translate it to HTML and other formats.

Unlike all other files in this package, the *.psi files in the directory
formats/psion are completely public domain. I ask anybody who reproduces
them, or uses their information in other programs, kindly to attribute
them to me.

The documentation files are not installed on a `make install'; you can
find them in the subdirectories of the formats directory.


THE LIBRARY
===========

libpsiconv is a library of routines that you can link against your own
application. It allows you to read and write Psion 5 files. Note that
it comes under the GNU General Public License; that means that you can
only link it to programs which are also covered by that license. You can
contact me if you need other license terms.

The following formats are supported at this moment:
  Word      (R+W) Word processor files
  TextEd    (R+W) OPL editor files
  Sketch    (R+W) Picture files
  MBM       (R+W) Alternate picture format; can contain several pictures
  ClipArt   (R+W) Internal picture format; can contain several pictures
  Sheet     (R)   Spreadsheet files

Documentation is scarce; please examine the source code or the example
psiconv program. Some things may also be found in the doc subdirectory.


THE PROGRAM
===========

Psiconv is a command-line converter that reads Psiconv files and outputs
more commonly used formats. It is linked against libpsiconv, and can
handle anything that it can.

Please enter `psiconv --help' if you want to know about its syntax.

The current HTML4 target is not very ideal. HTML is just not made to 
represent detailed layout considerations: it is a document description
language. Still, the output is quite readable already. Of course, headers
and footers are not displayed, because there is no notion of pages in 
HTML. Tabs are also difficult; they are not supported yet. This can be
solved using tables, but it is quite hard to do it correctly. Some other
things are just approximated too.

The XHTML target uses cascading style sheets (CSS). You need a not-too-old
browser for this to display correctly. Generally, the output of this
generator is of higher quality than the normal HTML generator's.

A plain TEXT target just grabs all text, without any futher conversions.

All ImageMagick graphic output formats are supported; depending on how
you compiled ImageMagick, this is betwee 20 and 50 different formats.
Your favorite one should be somewhere in there...

In the past, my focus was on extending the number of output targets for
this program; at the moment, I belief more in import/export filters for
office applications like AbiWord, Gnumeric and the Gimp.

Psiconv is licensed under the GPL. Please read the included file COPYING
for exact licensing information. Please contact me if you need some other
licensing terms.


NEWS AND FUTURE DEVELOPMENTS
============================

Starting with version 0.2, psiconv should keep all namespaces unpolluted.
Starting with version 0.4, the conversion routines are linked into a
(static or shared) library. Version 0.5 has autoconf and libtool support,
and should run on many more platforms. Version 0.6 has support for
graphics. Version 0.8 can generate files and add Sheet support. Version 
0.9 uses Unicode inside, add the psiconv.conf file and has many more
enhancements.

High on the TODO list are input routines for Record files. I am running into
some trouble understanding Data and Agenda files, but with a little luck, I'll
figure it out after all. This is more long-term though.


INSTALLATION
============

Please read the file INSTALL for installation instructions.
1	frodo	2	INTRODUCTION
2			============
3
4			This package is meant to make the Psion 5 series of PDAs, as well as other
5	frodo	200	small computers running EPOC 32, more usable to non-Windows users. But even
6	frodo	2	they may profit from the data I collected.
7
8			The package consists of several parts:
9			* Documentation about Psion 5 data formats;
10			* A library which can be linked against application that have to read
11	frodo	152	and write Psion 5 files;
12	frodo	2	* An example command-line program which reads Psion files and writes
13			more commonly used formats.
14
15
16			DATA FORMATS
17			============
18
19			As far as I know, and have gathered from the newsgroups, Psion does not want
20			or is not able to release the data formats of the saved files of their
21			internal applications. I am trying to reverse engineer these data formats
22			and to document them for general use. At this moment, I understand their
23	frodo	152	Word, Sheet, TextEd, Sketch, MBM, Clipart and Record files, as well as a
24			few other less important formats. I want this information to be available
25			to everyone, in order to write better file conversion utilities for popular
26			(non-)Windows programs.
27	frodo	2
28			All documentation is written in Psion 5 Word. Fortunately, the utilities
29			in this package can translate it to HTML and other formats.
30
31			Unlike all other files in this package, the *.psi files in the directory
32			formats/psion are completely public domain. I ask anybody who reproduces
33			them, or uses their information in other programs, kindly to attribute
34			them to me.
35
36			The documentation files are not installed on a `make install'; you can
37			find them in the subdirectories of the formats directory.
38
39
40			THE LIBRARY
41			===========
42
43			libpsiconv is a library of routines that you can link against your own
44	frodo	200	application. It allows you to read and write Psion 5 files. Note that
45			it comes under the GNU General Public License; that means that you can
46			only link it to programs which are also covered by that license. You can
47			contact me if you need other license terms.
48	frodo	2
49	frodo	200	The following formats are supported at this moment:
50			Word (R+W) Word processor files
51			TextEd (R+W) OPL editor files
52			Sketch (R+W) Picture files
53			MBM (R+W) Alternate picture format; can contain several pictures
54			ClipArt (R+W) Internal picture format; can contain several pictures
55			Sheet (R) Spreadsheet files
56	frodo	46
57	frodo	36	Documentation is scarce; please examine the source code or the example
58			psiconv program. Some things may also be found in the doc subdirectory.
59
60
61			THE PROGRAM
62			===========
63
64			Psiconv is a command-line converter that reads Psiconv files and outputs
65			more commonly used formats. It is linked against libpsiconv, and can
66			handle anything that it can.
67
68			Please enter `psiconv --help' if you want to know about its syntax.
69
70	frodo	200	The current HTML4 target is not very ideal. HTML is just not made to
71	frodo	2	represent detailed layout considerations: it is a document description
72			language. Still, the output is quite readable already. Of course, headers
73			and footers are not displayed, because there is no notion of pages in
74			HTML. Tabs are also difficult; they are not supported yet. This can be
75			solved using tables, but it is quite hard to do it correctly. Some other
76			things are just approximated too.
77
78	frodo	200	The XHTML target uses cascading style sheets (CSS). You need a not-too-old
79			browser for this to display correctly. Generally, the output of this
80			generator is of higher quality than the normal HTML generator's.
81	frodo	2
82			A plain TEXT target just grabs all text, without any futher conversions.
83
84	frodo	36	All ImageMagick graphic output formats are supported; depending on how
85			you compiled ImageMagick, this is betwee 20 and 50 different formats.
86	frodo	46	Your favorite one should be somewhere in there...
87	frodo	36
88	frodo	200	In the past, my focus was on extending the number of output targets for
89			this program; at the moment, I belief more in import/export filters for
90			office applications like AbiWord, Gnumeric and the Gimp.
91	frodo	2
92			Psiconv is licensed under the GPL. Please read the included file COPYING
93			for exact licensing information. Please contact me if you need some other
94			licensing terms.
95
96
97			NEWS AND FUTURE DEVELOPMENTS
98			============================
99
100	frodo	358	Starting with version 0.2, psiconv should keep all namespaces unpolluted.
101	frodo	2	Starting with version 0.4, the conversion routines are linked into a
102			(static or shared) library. Version 0.5 has autoconf and libtool support,
103	frodo	36	and should run on many more platforms. Version 0.6 has support for
104	frodo	200	graphics. Version 0.8 can generate files and add Sheet support. Version
105			0.9 uses Unicode inside, add the psiconv.conf file and has many more
106			enhancements.
107	frodo	2
108	frodo	358	High on the TODO list are input routines for Record files. I am running into
109			some trouble understanding Data and Agenda files, but with a little luck, I'll
110			figure it out after all. This is more long-term though.
111	frodo	2
112
113			INSTALLATION
114			============
115
116			Please read the file INSTALL for installation instructions.
frodo@frodo.looijaard.name	ViewVC Help
Powered by ViewVC 1.1.26