updated NEWS and ChangeLogs about new proplist code in WINGs before a new release

ChangeLog

@@ -25,7 +25,8 @@ Changes since version 0.65.1:
   compatibility header file is provided which maps old libPropList
   function names to the new WINGs based proplist names allowing old code
   to be linked to WINGs with minimal changes. For details on how to use
-  the compat mode, read the comments on the top of WINGs/proplist-compat.h
+  the compat mode, read the comments on top of WINGs/WINGs/proplist-compat.h
+  More details about this can be found in WINGs/ChangeLog and WINGs/NEWS.
   Say bye, bye libPropList =)
 - rewrote all Window Maker code to use the new WINGs based proplist functions.
 - fixed a few compilation warnings and a problem caused by an uninitialized 

NEWS

@@ -18,8 +18,12 @@ Less dependancies
 
 starting with 0.70.0 libPropList is no longer required to build Window
 Maker. PropList handling code was added to WINGs being now better
-integrated with all the rest. For more details check the Changelog
-./WINGs/NEWS, ./WINGs/WINGs/WUtil.h and ./WINGs/WINGs/proplist-compat.h
+integrated with all the rest. For more details check the Changelog and the 
+following files:
+./WINGs/ChangeLog
+./WINGs/NEWS
+./WINGs/WINGs/WUtil.h
+./WINGs/WINGs/proplist-compat.h
 
 
 

WINGs/ChangeLog

@@ -7,7 +7,8 @@ Changes since wmaker 0.65.0:
 - added property list handling code making libPropList unnecessary and
   obsolete. Backward compatibility is provided through the 
   WINGs/proplist-compat.h header file which has #defines from old libPropList
-  function names to new function names with minimal changes.
+  function names to new function names with minimal changes. Read this
+  header file and the NEWS file for more details about this subject.
 - Renamed WMGetUDAllKeys() to WMGetUDKeys()
 
 

WINGs/NEWS

@@ -6,15 +6,49 @@ Property lists handling code
 
 Code to handle property lists was added to WINGs. It is more robust
 than the libPropList code, mostly because some conflicting concepts 
-borrowed from UserDefaults (which libPropList uses) are no longer used in
-the property lists code.
-It is also better integrated with the other data types from WINGs.
+borrowed from UserDefaults (which libPropList use) are no longer used in
+the WINGs property lists code. These borrowed concepts conflicted with the
+retain/release mechanism of property lists and could lead in certain cases
+to segmentation faults when executing libPropList based code. But the worse
+part was that these libPropList problems were practically unsolvable without
+removing one of those conflicting concepts and without a complete redesign. 
+The new WINGs property lists code is also better integrated with the other
+data types from WINGs and is actively maintained.
 
-Old libPropList based code can still run with the new WINGs proplist
-code with minimal changes which are described in detail in the comments
-at the top of the WINGs/proplist-compat.h header file (the same file
-carries the #defines for mapping old libPropList functions to the new
-WINGs proplist functions).
+Practically the things that were removed from the WINGs property list
+implementation compared to the old libPropList implementation, are exactly
+the UserDefaults borrowed concepts that conflict with the retain/release
+mechanism:
+- The container of a proplist object and the associated functions are gone.
+- The filename associated with a proplist object and the corresponding
+  functions are gone. Now the saving function needs the filename as a
+  parameter.
+- The synchronization functions are no longer supported. They are part of
+  the UserDefaults and are implemented there.
+- No functions related to domains/registering were implemented in the WINGs
+  property lists code, because they are also not part of property lists.
+  They are more in connection with UserDefaults and a central point of access
+  for domains.
+
+The above 2 concepts: container and filename were added to libPropList just
+to let it support synchronization which was borrowed from UserDefaults.
+Property lists as defined in the openstep specification are just complex
+data structures composed of strings, data, arrays, dictionaries and a mix of
+them and are not associated with any file in particular. UserDefaults on the
+other hand are property lists read from a specific file and they associate
+that property list with that file and allow them to be synchronized.
+
+Old libPropList based code can still be used by linking against the WINGs
+library containing the new proplist code with minimal changes which are
+described in detail in the comments at the top of the WINGs/proplist-compat.h
+header file (the same file carries the #defines for mapping old libPropList
+functions to the new WINGs proplist functions).
+Our recommendation is to move to the new functions WINGs provide because
+they better integrate with other function naming conventions in WINGs.
+The proplist-compat.h header file is just a way to have old code up and
+running with minimal changes so that we can remove the old and unmaintained
+libPropList from systems while keeping to use old libPropList based code
+without rewriting it and it should not be used for other purposes.
 
 
 *** Sat Apr 21 09:12:09 EEST 2001 -Dan

WINGs/WINGs/WUtil.h

@@ -805,7 +805,7 @@ WMPropList* WMGetFromPLDictionary(WMPropList *plist, WMPropList *key);
 
 /* Returns a PropList array with all the dictionary keys. Release it when
  * you're done. Keys in array are retained from the original dictionary
- * not copied */
+ * not copied and need NOT to be released individually. */
 WMPropList* WMGetPLDictionaryKeys(WMPropList *plist);
 
 /* Creates only the first level deep object. All the elements inside are
@@ -817,7 +817,7 @@ WMPropList* WMDeepCopyPropList(WMPropList *plist);
 
 WMPropList* WMCreatePropListFromDescription(char *desc);
 
-/* Free the returned string when you're done */
+/* Free the returned string when you no longer need it */
 char* WMGetPropListDescription(WMPropList *plist, Bool indented);
 
 WMPropList* WMReadPropListFromFile(char *file);

WINGs/WINGs/proplist-compat.h

@@ -61,6 +61,16 @@
 
 typedef WMPropList* proplist_t;
 
+
+#ifndef YES
+#define YES True
+#endif
+
+#ifndef NO
+#define NO False
+#endif
+
+
 #define PLSetCaseSensitive(c) WMPLSetCaseSensitive(c)
 
 #define PLMakeString(bytes) WMCreatePLString(bytes)
@@ -108,22 +118,21 @@ typedef WMPropList* proplist_t;
 #define PLSave(pl, file, atm) WMWritePropListToFile(pl, file, atm)
 
 
-#if 0
-#define PLSetStringCmpHook(fn)
-#define PLDeepSynchronize(pl) PLDeepSynchronize_is_not_supported
-#define PLSynchronize(pl) PLSynchronize_is_not_supported
+/* Unsupported functions. Do not ask for them. They're evil :P */
+#define PLSetStringCmpHook(fn) error_PLSetStringCmpHook_is_not_supported
+#define PLDeepSynchronize(pl) error_PLDeepSynchronize_is_not_supported
+#define PLSynchronize(pl) error_PLSynchronize_is_not_supported
 #define PLShallowSynchronize(pl) error_PLShallowSynchronize_is_not_supported
 #define PLSetFilename(pl, filename) error_PLSetFilename_is_not_supported
 #define PLGetFilename(pl, filename) error_PLGetFilename_is_not_supported
-#define PLGetContainer(pl)
+#define PLGetContainer(pl) error_PLGetContainer_is_not_supported
 
-#define PLGetDomainNames()
-#define PLGetDomain(name)
-#define PLSetDomain(name, value, kickme)
-#define PLDeleteDomain(name, kickme)
-#define PLRegister(name, callback)
-#define PLUnregister(name)
-#endif
+#define PLGetDomainNames error_PLGetDomainNames_is_not_supported
+#define PLGetDomain(name) error_PLGetDomain_is_not_supported
+#define PLSetDomain(name, value, kickme) error_PLSetDomain_is_not_supported
+#define PLDeleteDomain(name, kickme) error_PLDeleteDomain_is_not_supported
+#define PLRegister(name, callback) error_PLRegister_is_not_supported
+#define PLUnregister(name) error_PLUnregister_is_not_supported
 
 
 #endif

src/.cvsignore

@@ -1,5 +1,5 @@
 Makefile Makefile.in
-config.h config.h.in wconfig.h stamp-h stamp-h.in
+config.h config.h.in wconfig.h stamp-h stamp-h1 stamp-h.in
 .libs
 wmaker
 .psrc .inslog2 tca.map tca.log