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 in the future, perhaps 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, TextEd, Sketch, MBM and Record files. 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, and helps you output
more commonly used 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.

Libpsiconv consists of two parts. The parser reads the Psion file into its
internal data structures. The generator reads these data structures and
generates an output file in some other format. Libpsiconv is written to make
it easy to add generators, without having to modify the parser side. 
Actually, it is a lot easier to write a generator than to modify the parser!

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. Of course, it can also not yet 
cope with inserted objects (ie. documents in some other format) and
other as of yet undocumented things.

The current HTML 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.

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!

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.

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. 

High on the TODO list are input routines for Sketch, MBM and 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			(and in the future, perhaps write) Psion 5 files;
12			* 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			Word, TextEd, Sketch, MBM and Record files. I want this information to
24			be available to everyone, in order to write better file conversion utilities
25			for popular (non-)Windows programs.
26
27			All documentation is written in Psion 5 Word. Fortunately, the utilities
28			in this package can translate it to HTML and other formats.
29
30			Unlike all other files in this package, the *.psi files in the directory
31			formats/psion are completely public domain. I ask anybody who reproduces
32			them, or uses their information in other programs, kindly to attribute
33			them to me.
34
35			The documentation files are not installed on a `make install'; you can
36			find them in the subdirectories of the formats directory.
37
38
39			THE LIBRARY
40			===========
41
42			libpsiconv is a library of routines that you can link against your own
43			application. It allows you to read Psion 5 files, and helps you output
44			more commonly used files. Note that it comes under the GNU General
45			Public License; that means that you can only link it to programs which
46			are also covered by that license. You can contact me if you need other
47			license terms.
48
49			Libpsiconv consists of two parts. The parser reads the Psion file into its
50			internal data structures. The generator reads these data structures and
51			generates an output file in some other format. Libpsiconv is written to make
52			it easy to add generators, without having to modify the parser side.
53			Actually, it is a lot easier to write a generator than to modify the parser!
54
55			The parser is quite good at the moment. Page layout codes are not yet
56			read, but almost everything that is described in the documents in the
57			format directory is supported by it. Of course, it can also not yet
58			cope with inserted objects (ie. documents in some other format) and
59			other as of yet undocumented things.
60
61			The current HTML target is not very ideal. HTML is just not made to
62			represent detailed layout considerations: it is a document description
63			language. Still, the output is quite readable already. Of course, headers
64			and footers are not displayed, because there is no notion of pages in
65			HTML. Tabs are also difficult; they are not supported yet. This can be
66			solved using tables, but it is quite hard to do it correctly. Some other
67			things are just approximated too.
68
69			The HTML4 target uses style sheets. You need a not-too-old browser for
70			this to display correctly. Generally, the output of this generator is
71			of higher quality than the normal HTML generator's.
72
73			A plain TEXT target just grabs all text, without any futher conversions.
74
75			I would very much like to add other targets, like (La)TeX, RTF (Rich Text
76			Format) and XML (for AbiWord). If other people want to work on this, please
77			let me know! Of course, you could also write your own conversion applications
78			just using my data format description. Native import/export filters for
79			some word processors would be very welcome!
80
81			Documentation is scarce; please examine the source code or the example
82			psiconv program. Some things may also be found in the doc subdirectory.
83
84
85			THE PROGRAM
86			===========
87
88			Psiconv is a command-line converter that reads Psiconv files and outputs
89			more commonly used formats. It is linked against libpsiconv, and can
90			handle anything that it can.
91
92			Please enter `psiconv --help' if you want to know about its syntax.
93
94			Psiconv is licensed under the GPL. Please read the included file COPYING
95			for exact licensing information. Please contact me if you need some other
96			licensing terms.
97
98
99			NEWS AND FUTURE DEVELOPMENTS
100			============================
101
102			Starting with version 0.2, psiconv should keep all namespaces unpoluted.
103			Starting with version 0.4, the conversion routines are linked into a
104			(static or shared) library. Version 0.5 has autoconf and libtool support,
105			and should run on many more platforms.
106
107			High on the TODO list are input routines for Sketch, MBM and Record files.
108			Sheet files will be next. I am running into some trouble understanding
109			Data and Agenda files, but with a little luck, I'll figure it out after
110			all. This is more long-term though.
111			On the output side, I hope RTF will soon be done. This will allow most
112			office tools to read the Psion files.
113
114
115			INSTALLATION
116			============
117
118			Please read the file INSTALL for installation instructions.
frodo@frodo.looijaard.name	ViewVC Help
Powered by ViewVC 1.1.26