Re: Patch: NSTimeZone

[Sheldon Gill]

> The restructuring of the comment on the mechanisms for specifying the
> local timezone looks like an improvement to me.

Thank you.

> The comments on the filesystem layout look reasonable but ...
> 1. I think filesystem documentation should reside in *one* place, and
> the comments in this file should just direct you to it.

Perhaps. I agree that there needs to be a single reference point for file 
system documentation so that you know where to look.

However, at the moment assumptions about the file system are scattered 
throughout the code. {NSBundle, NSUser, GSLocale, NSTimeZone, NSFileHandle, 
NSTask, NSUserDefaults, NSMessagePort... }
There isn't any one place for this to go. Yet.

Also, in order to understand what the NSTimeZone code does you need to know 
about the file system assumptions and decisions. It makes sense to me to 
document that in the code where it's used so that you can work on just this 
module. I think it makes it easier to assess the design and impact of 
changes. It's of more interest to the developer than anyone else.

My feeling is that detailed techinical 'File System Information' should be put 
into those modules which make decisions or assumptions. We can then create an 
overview document which contains references to these details.
Perhaps we could even extend autogsdoc to create it all automatically as part 
of base developer documentation?

My idea is that the GFHS states the standard. Intended audience is all users.
The developer overview doc tells you what is what and where. The intended 
audience is application developers and power users.
The comments in the modules tell you how and why. The intended audience is 
gnustep-core developers and those seeking to extend/over-ride those 
libraries.

> 2. I'm not sure about suggesting linking to existing posix files

I'm trying not to "suggest" that this is done but rather noting that it can be 
done. If that's not too clear perhaps it needs to be re-phrased.
They are "time zone information files" from the Olson database. Glibc, Solaris 
and many others use the same source. There is _no_ difference in the content 
of those files or their file names. GNUstep simply adds the GMT-14 to GMT+14 
zone files and generates "regions" and "abbreviations".
The current gnustep distribution uses 2002 rev c which has been superseeded. 
The files are now outdated for Iran, MST, NZ, Portugal, Canada, Europe/
Berlin, parts of America etc
GNUstep needs to maintain a current distribution of this data. By linking to 
information provided by someone else this maintenance burden can be eased.
The GMT zones are geographic regions, unencumbered with politics. They won't 
change.

> Perhaps you could re-do this with a patch which maintains the existing
> use of spaces/tabs/indentation?

Here it is:

NSTimeZone_documentation.patch
Description: Text Data

NSTimeZone_documentation.patch.changelog
Description: Text document