1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
/-----------------------------------------------------------------------------
| $Log: README,v $
| Revision 1.1 2002/10/11 14:08:59 monos
| *** empty log message ***
|
| Revision 1.13 2001/12/28 17:29:29 tilda
| Minor tidy ups after updating to DevIL-1.2.4
|
| Revision 1.12 2001/12/16 16:01:15 tilda
| Update release notes before Alpha-5
|
| Revision 1.11 2001/12/10 09:28:35 tilda
| Typo.
|
| Revision 1.10 2001/12/10 09:21:47 tilda
| Describe image librrary build options.
|
| Revision 1.9 2001/12/02 21:20:25 tilda
| Update prior to Alpha-4
|
| Revision 1.8 2001/11/27 18:32:59 tilda
| Reword LICENCING section in README.txt. Move docs into vformatl.dsp
|
\-----------------------------------------------------------------------------
Welcome to the vFormat Library!
LICENCE
=======
All this software (the library and the demo apps) is distributed under the
GNU Lesser General Public Licence. A copy of this is distributed with the
library - see the file LICENCE.txt in the libraries root directory.
Please read and understand the comments at the top of vf_iface.h before use.
RELEASES
========
This will be considered "alpha" until all the features I think should be
there are there. It'll be "beta" until I know of no outstanding issues.
Release history:
Alpha-1 : first cut at a release, known problems with BASE64, no create/modify API
Alpha-2 : BASE64 encoding fixed, first pass at create/modify functionality
Alpha-3 : including first usable version of vfedit demo app
Alpha-4 : Add basic framework support for vCalendar to VFEDIT. Sort out tools menu
and font manager. Fix IIDs 485069, 485071, 488003, 484956, 488006, 488011.
Sort out various bugs in IMGHLP DLLs.
Alpha-5 : Various bug fixes and move to use of a image library (DevIL from SourceForge)
rather than various dodgy home-grown bits'n'pieces. Fix IIDs 484685, 491475
489753, 484684, 488021, 484958, 484844, 484843. vfedit now reasonably usable
(for VCARDs).
BUILDING
========
Under Windows, the build uses Microsoft's Visual C++ version 6.0 - the
project & workspace files are included in the distribution. The workspace
at .../build/vformat/vformat.dsw references will build and install the
library (ie. the .DLL) and builds the test harness. In detail:
.../build/vformat/vformat.dsw - workspace including other project files
.../build/vformatl/vformatl.dsp - builds (and installs) DLL version
.../build/tools - various tools & utilities
.../build/vfdisplay - minimal app enumerating contents of a vobject
.../build/vfedit - demo app supporting VCARDs & VCALENDARs.
Beware - vformatl.dsp and the other DSPs will install the DLLs in your
windows/system directory using the INSDLL.BAT file in the tools directory
which is invoked as a post-build step (see the post-build tab on the
projects/settings dialog). If you don't like this, delete the post
build step or edit the script to put the DLL somewhere else.
IMAGE LIBRARY
=============
Imaging formats (.JPG etc) are handled in the demo applications using a 3rd party
open source image library. Early releases of VFEDIT used various bits of garbage
I'd collected over the years wrapped up in an .DLL (deliberately hiding the crap).
As of Alpha-5, VFEDIT includes support for DevIL - the Developer's Image Libray.
Details of this can be found at http://OpenIL.sourceforge.net.
To enable image support you need to download & install DevIL and change the line
at the top of ImageManager.cpp to #define USE_IMAGE_LIBRARY (rather than #undef).
Here are the instructions to get a basic version of this going, this is based on
the install instructions included in DevIL & various things about my machine. The
basic version supports .BMP files, I've not (yet) got round to adding .JPG etc to
my build of DevIL.
- download DevIL-1.2.4.zip from the page in SourceForge.
- unpack the .ZIP file somewhere convenient eg. D:\DevIL
- change your global include paths (eg. Tools->Options->Directories in MSVC6)
to include DevIL's include dirs (eg. D:\DevIL\ImageLib\Include)
- change your global library paths to include DevIL's include dirs
(eg. D:\DevIL\ImageLib\lib and D:\DevIL\ImageLib\lib\debug)
- change the post build steps as appropriate for your system
- uncomment IL_NO_GIF, IL_NO_JPG, IL_NO_MNG, IL_NO_PNG, IL_NO_TIF
- uncomment IL_NO_LCMS and comment out ilApplyProfile from IL.DEF
- comment out ILUT_USE_DIRECTX8 in il/ilut.h (I don't have it installed)
- comment out ilutD3D8LoadSurface ... ilutD3D8VolTexFromResource from ILUT.def
- change the USE_IMAGE_LIBRARY #define in ImageManager.cpp
REFERENCES
==========
[1] vCard, The Electronic Business Card Version 2.1 from Versit.
OUTSTANDING ISSUES
==================
After Alpha-4, this section transferred to the SourceForge database.
THE TEST HARNESS
================
Running the test harness will produce a load of output similar to
the following:
--tests//adhoc//straight_qp_4.vcf------------------------------------------
Successfully read file 'tests//adhoc//straight_qp_4.vcf'
Successfully wrote file 'vobject.vcf'
Successfully wrote file 'tests//adhoc//straight_qp_4.out-1'
Sizes difference :
tests//adhoc//straight_qp_4.out-1 (139 bytes) Vs.
tests//adhoc//straight_qp_4.vcf (151 bytes)
Warning - differences after 1st read/write
Successfully read file 'tests//adhoc//straight_qp_4.out-1'
Successfully wrote file 'tests//adhoc//straight_qp_4.out-2'
OK - no differences after 2nd read/write
[60 tests, 0 errors, 13 warnings]
What does it all mean? All the warnings are a result of size differences
between the original file & the result of reading/writing the file back.
The size differences are a result of:
* slightly different conventions for line length
* line ends (eg <LF> not <CR><LF>)
* different selection of quoted chars in QP format
* excess whitespace at the end of the file
* characters ignored before the first BEGIN: or between END: and BEGIN:
Each such difference is clocked up as a warning. The [...] stuff is
a rolling count of tests, errors & warnings. An error is logged if
after the file is "canonicalised" (well; into the format assumed by
this library anyway) we fail to read & write and get the same output.
The files in tests/spec are named after sections of the (very fine)
vcard 2.1 specification eg. 2_1_4_1-grouping-sequential.vcf will refer
to something like "sequential grouping" in section 2.1.4.1 of the
Versit doc (see http://www.imc.org/pdi/ for the docs).
(There is no intention to infringe the copyright anyone might consider
they have vested in the text of these examples)
The files in tests/adhoc are just sample scripts I knocked up
during development.
FUTURE PLANS
============
1) Convert this document to some decent on-line docs on the project website.
2) Write a vobjects library .../src/vobjects & .../build/vobjectsl which
provides C++ classes modelling a vformat object with derived classes
for vCard, vNote etc. Functions on the base class provide file handling
and change logs. Functions on the derived classes handle a user's
normal interaction with the relevant objects eg:
typedef enum
{
Work,
Home,
Cellular,
Mobile = Cellular
}
vf_phone_type_t;
bool_t vformat::vcard::set_phone_no(
vf_phone_type_t t, /* Type of phone number */
bool_t is_pref, /* Should this entry be given the PREF flag? */
const char *phone_no /* The phone number itself */
);
4) Duplicate the MFC app as a GTK app.
CREDITS
=======
Enjoy!
Nick <Tilda@indigo8.freeserve.co.uk>
|
