diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 207 |
1 files changed, 207 insertions, 0 deletions
@@ -0,0 +1,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> |