summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorGravatar Nikias Bassen2013-02-10 20:06:08 +0100
committerGravatar Nikias Bassen2013-02-10 20:06:08 +0100
commitd3a53b82aa57f5090d95b69e6f567b06eb544df9 (patch)
tree953480ca4db7109376a6ca422971bd6481efcc78 /README
downloadlibvformat-d3a53b82aa57f5090d95b69e6f567b06eb544df9.tar.gz
libvformat-d3a53b82aa57f5090d95b69e6f567b06eb544df9.tar.bz2
initial commit of 1.13 sources
Diffstat (limited to 'README')
-rw-r--r--README207
1 files changed, 207 insertions, 0 deletions
diff --git a/README b/README
new file mode 100644
index 0000000..d27d423
--- /dev/null
+++ b/README
@@ -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>