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 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 can be read at this moment:
  Word      Word processor files
  TextEd    OPL editor files
  Sketch    Picture files
  MBM       Alternate picture format; several pictures can be combined in it
  ClipArt   Internal picture format; several pictures can be combined in it

The parser is quite good at the moment. Page layout codes are not yet
read, but almost everything that is described in the documents in the
format directory is supported by it; but it can not yet cope with 
inserted objects (ie. documents in some other format).

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 HTML3 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 HTML4 target uses style sheets. 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.

The RTF target is not finished yet; in fact, it is no usable at all
right now.

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...

I would very much like to add other targets, like (La)TeX, RTF (Rich Text
Format) and XML (for AbiWord). If other people want to work on this, please
let me know! Of course, you could also write your own conversion applications
just using my data format description. Native import/export filters for
some word processors would be very welcome!

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 unpoluted.
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.

High on the TODO list are input routines for Record files. 
Sheet files will be next. 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.
On the output side, I hope RTF will soon be done. This will allow most
office tools to read the Psion files.


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			small computers running Epoc 32, more usable to non-Windows users. But even
6			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	36	application. It allows you to read Psion 5 files. Note that it comes
45			under the GNU General Public License; that means that you can only link
46			it to programs which are also covered by that license. You can contact
47			me if you need other license terms.
48	frodo	2
49	frodo	46	The following formats can be read at this moment:
50			Word Word processor files
51			TextEd OPL editor files
52			Sketch Picture files
53			MBM Alternate picture format; several pictures can be combined in it
54			ClipArt Internal picture format; several pictures can be combined in it
55
56	frodo	2	The parser is quite good at the moment. Page layout codes are not yet
57			read, but almost everything that is described in the documents in the
58	frodo	46	format directory is supported by it; but it can not yet cope with
59			inserted objects (ie. documents in some other format).
60	frodo	2
61	frodo	36	Documentation is scarce; please examine the source code or the example
62			psiconv program. Some things may also be found in the doc subdirectory.
63
64
65			THE PROGRAM
66			===========
67
68			Psiconv is a command-line converter that reads Psiconv files and outputs
69			more commonly used formats. It is linked against libpsiconv, and can
70			handle anything that it can.
71
72			Please enter `psiconv --help' if you want to know about its syntax.
73
74			The current HTML3 target is not very ideal. HTML is just not made to
75	frodo	2	represent detailed layout considerations: it is a document description
76			language. Still, the output is quite readable already. Of course, headers
77			and footers are not displayed, because there is no notion of pages in
78			HTML. Tabs are also difficult; they are not supported yet. This can be
79			solved using tables, but it is quite hard to do it correctly. Some other
80			things are just approximated too.
81
82			The HTML4 target uses style sheets. You need a not-too-old browser for
83			this to display correctly. Generally, the output of this generator is
84			of higher quality than the normal HTML generator's.
85
86			A plain TEXT target just grabs all text, without any futher conversions.
87
88	frodo	36	The RTF target is not finished yet; in fact, it is no usable at all
89			right now.
90
91			All ImageMagick graphic output formats are supported; depending on how
92			you compiled ImageMagick, this is betwee 20 and 50 different formats.
93	frodo	46	Your favorite one should be somewhere in there...
94	frodo	36
95	frodo	2	I would very much like to add other targets, like (La)TeX, RTF (Rich Text
96			Format) and XML (for AbiWord). If other people want to work on this, please
97			let me know! Of course, you could also write your own conversion applications
98			just using my data format description. Native import/export filters for
99			some word processors would be very welcome!
100
101			Psiconv is licensed under the GPL. Please read the included file COPYING
102			for exact licensing information. Please contact me if you need some other
103			licensing terms.
104
105
106			NEWS AND FUTURE DEVELOPMENTS
107			============================
108
109			Starting with version 0.2, psiconv should keep all namespaces unpoluted.
110			Starting with version 0.4, the conversion routines are linked into a
111			(static or shared) library. Version 0.5 has autoconf and libtool support,
112	frodo	36	and should run on many more platforms. Version 0.6 has support for
113			graphics.
114	frodo	2
115	frodo	36	High on the TODO list are input routines for Record files.
116	frodo	2	Sheet files will be next. I am running into some trouble understanding
117			Data and Agenda files, but with a little luck, I'll figure it out after
118			all. This is more long-term though.
119			On the output side, I hope RTF will soon be done. This will allow most
120			office tools to read the Psion files.
121
122
123			INSTALLATION
124			============
125
126			Please read the file INSTALL for installation instructions.
frodo@frodo.looijaard.name	ViewVC Help
Powered by ViewVC 1.1.26