diff --git a/Source/Base.gsdoc b/Source/Base.gsdoc new file mode 100644 index 000000000..84a667c36 --- /dev/null +++ b/Source/Base.gsdoc @@ -0,0 +1,304 @@ + + + + + GNUstep Base + + + + + $Revision$ + $Date$ + + + + Base +

+ The GNUstep base library is a free software package implementing + the API of the OpenStep Foundation Kit (tm), including later + additions. +

+
+ Compatibility +

+ GNUstep is generally compatible with the OpenStep specification and + with recent developments of the MacOS (cocoa) API. Where MacOS + deviates from the OpenStep API, GNUstep generally attempts to + support both versions. In some cases the newer MacOS APIs are + incompatible with OpenStep, and GNUstep usually supports the richer + version. +

+

+ In order to deal with compatiblity issues, GNUstep uses two + mechanisms - it provides conditionally compiled sections of + the library header files, so that software can be built that + will conform strictly to a particular API, and it provides + user default settings to control the behavior of the library + at runtime. +

+ + Conditional compilation +

+ Adding an option to a makefile to define one of the following + preprocessor constants will modify the API visible to software + being compiled - +

+ + NO_GNUSTEP + + GNUstep specific extensions to the OpenStep and MacOS cocoa + APIs are excluded from the headers. + + STRICT_MACOS_X + + Only methods and classes that are part of the MacOS cocoa + API are made available in the headers. + + STRICT_OPENSTEP + + Only methods and classes that are part of the OpenStep + specification are made available in the headers. + + + + + User defaults + + GSLogSyslog + +

+ Setting the user default GSLogSyslog to + YES will cause log/debug output to be sent to + the syslog facility (on systems which support it), rather + than to the standard error stream. This is useful in + environments where stderr has been re-used strangely for + some reason. +

+ + GSMacOSXCompatible + +

+ Setting the user default GSMacOSXCompatible to + YES will cause MacOS compatible behavior to be + the default at runtime. This default may however be overridden + to provide more fine grained control of system behavior. +

+ + GSOldStyleGeometry + +

+ Specifies whether the functions for producing strings + describing geometric structures (NSStringFromPoint(), + NSStringFromSize(), and NSStringFromRect()) should produce + strings conforming to the OpenStep specification or to + MacOS-X behavior. The functions for parsing those strings + should cope with both cases anyway. +

+ + NSWriteOldStylePropertyLists + +

+ Specifies whether text property-list output should be in + the default MacOS-X format (XML), or in the more human + readable (but less powerful) original OpenStep format. +

+

+ Reading of property lists is supported in either format, + but only if GNUstep is built with the libxml + library (which is needed to handle XML parsing). +

+

+ NB. MacOS-X generates illegal XML for some strings - those + which contain characters not legal in XML. GNUstep always + generates legal XML, at the cost of a certain degree of + compatibility. GNUstep XML property lists use a backslash + to escape illegal chatracters, and consequently any string + containing either a backslash or an illegal character will + be written differently to the same string on MacOS-X. +

+ + NSLanguages + +

+ An array of strings that lists the users prefered languages, + in order or preference. If not found the default is just + English. +

+ + + + + Environment variables +

+ There are some environment variables used by GNUstep base, where + there would be problems onbtaining data from the defaults asystem. +

+ + CRASH_ON_ABORT + +

+ The default exception handler will either cause the program to + simply terminate, or to crash - leaving a core dump. The + standard behavior is to leave a core dump if the library was + built for debugging, and to simply exit if it was not. +

+

+ The CRASH_ON_ABORT environment variable can be used to + override this behavior. If this is defined to NO, + FALSE, or 0 then the program will simply + exit when an exception occurs. Any other value of the + variable will cause the program to generate a core dump. +

+ + GNUSTEP_STRING_ENCODING + +

+ This is used to specify the default encoding for 8-bit + strings. It defaults to NSISOLatin1StringEncoding, but + may be any of the 8-bit encodings supported by your system + (excluding multi-byte encodings). +

+ + GNUSTEP_HOST_CPU + +

+ Used in place of GNUSTEP_TARGET_CPU if the other is missing. +

+ + GNUSTEP_HOST_DIR + +

+ Used in place of GNUSTEP_TARGET_DIR if the other is missing. +

+ + GNUSTEP_HOST_OS + +

+ Used in place of GNUSTEP_TARGET_OS if the other is missing. +

+ + GNUSTEP_LOCAL_ROOT + +

+ Used to specify the GNUstep root directory for local + (non-system) resources. Typically all locally produced + or contributed software is installed relative to this. +

+ + GNUSTEP_NETWORK_ROOT + +

+ Used to specify the GNUstep root directory for local + (non-system) resources that are intended to be shared + across a local network. Typically this is an NFS exported + directory shared by many machines. It provides an + alternative to GNUSTEP_LOCAL_ROOT. +

+ + GNUSTEP_SYSTEM_ROOT + +

+ Used to specify the GNUstep system root directory ... all + system libraries, tools, applications, headers, resources + in general are located relative to this. +

+ + GNUSTEP_USER_ROOT + +

+ Used to specify the GNUstep directory in which resources + specific to the current user are located. +

+ + GNUSTEP_TARGET_CPU + +

+ Overrides the default value of the machine (hardware) + name used on this system. +

+ + GNUSTEP_TARGET_DIR + +

+ Overrides the default path used to locate subdirectories + for GNUstep binaries withing bundles and applications. + This is normally equivalent to a path made up of the + GNUSTEP_TARGET_CPU and GNUSTEP_TARGET_OS +

+ + GNUSTEP_TARGET_OS + +

+ Overrides the default value of the operating system + name used on this system. +

+ + GNUSTEP_TZ + +

+ Used to specify the timezone to be used if there is no + timezone specified in the user defaults system. + The preferred + mechanism is to use the 'Local Time Zone' value from the + user defaults system. +

+ + HOMEDRIVE + +

+ Used on windoze to locate the home directory. +

+ + HOMEPATH + +

+ Used on windoze to locate the home directory. +

+ + LANGUAGES + +

+ If there is no NSLanguages user default set, and there is + no language infromation available in the native system locale + mechanism, then this environment variable is used to provide + a list of the languages that the user prefers to use. + languages listed in this variable must be separated by + semicolons. +

+ + LOGNAME + +

+ This is used as the default value for the current user + (as returned by the NSUserName() functions). If it is not + specified, or contains an illegal value, other methods are + used to get the user name. +

+ + LIBRARY_COMBO + +

+ Used to override the default value of the combination + of standard libraries used to build binaries. This + value locates the final subdirectory used to locate binaries. +

+ + TZ + +

+ Used to specify the timezone to be used if there is no + timezone specified by any other mechanism. The preferred + mechanism is to use the 'Local Time Zone' value from the + user defaults system. +

+ + + + +
+ + + + + + diff --git a/Source/GNUmakefile b/Source/GNUmakefile index 8a644d84b..054ba2be1 100644 --- a/Source/GNUmakefile +++ b/Source/GNUmakefile @@ -315,8 +315,7 @@ win32-load.h \ NSCallBacks.h \ tzfile.h -FOUNDATION_HEADERS = \ -Foundation.h \ +AUTOGSDOC_HEADERS = \ GSMime.h \ GSXML.h \ NSArchiver.h \ @@ -379,14 +378,16 @@ NSTask.h \ NSThread.h \ NSTimeZone.h \ NSTimer.h \ +NSURL.h \ +NSURLHandle.h \ NSUndoManager.h \ NSUserDefaults.h \ NSUtilities.h \ NSValue.h \ -NSZone.h \ -objc-load.h \ -NSURL.h \ -NSURLHandle.h +NSZone.h + +FOUNDATION_HEADERS = Foundation.h $(AUTOGSDOC_HEADERS) objc-load.h + UNICODE_HEADERS = \ unicode/caseconv.h \ @@ -428,7 +429,7 @@ libgnustep-base_HEADER_FILES = $(FOUNDATION_HEADERS) DOCUMENT_NAME = Base -Base_AGSDOC_FILES = $(FOUNDATION_HEADERS) +Base_AGSDOC_FILES = Base.gsdoc $(AUTOGSDOC_HEADERS) Base_AGSDOC_FLAGS = \ -HeaderDirectory ../Headers/Foundation \ -Declared Foundation \ diff --git a/Source/GSXML.m b/Source/GSXML.m index 2ee062dc1..8b8dd6700 100644 --- a/Source/GSXML.m +++ b/Source/GSXML.m @@ -1,4 +1,4 @@ -/** Implementation for GSXMLDocument for GNUstep xmlparser +/** Implementation for GSXML classes Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. @@ -24,6 +24,19 @@ You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA. + + The XML and HTML parsing system + + The XML and HTML parsing system +

+ The GNUstep XML parser is a collection Objective-C classes + wrapping the C XML parsing library (libxml). +

+

+ The underlying C library handles high performance parsing, while + the ObjectiveC classes provide ease of use/integration. +

+ */ #include @@ -131,7 +144,6 @@ loadEntityFunction(const char *url, const char *eid, xmlParserCtxtPtr *ctxt); /** * Create a new document with the specified version. * - * * id d = [GSXMLDocument documentWithVersion: @"1.0"]; * * [d setRoot: [d makeNodeWithNamespace: nil name: @"plist" content: nil]]; @@ -142,7 +154,6 @@ loadEntityFunction(const char *url, const char *eid, xmlParserCtxtPtr *ctxt); * [n1 makeChildWithNamespace: nil name: @"key" content: @"Year Of Birth"]; * [n1 makeChildWithNamespace: nil name: @"integer" content: @"65"]; * [n1 makeChildWithnamespace: nil name: @"key" content: @"Pets Names"]; - * * */ + (GSXMLDocument*) documentWithVersion: (NSString*)version @@ -280,7 +291,6 @@ loadEntityFunction(const char *url, const char *eid, xmlParserCtxtPtr *ctxt); /** * Creates a new node within the document. * - * * GSXMLNode *n1, *n2; * GSXMLDocument *d; * @@ -288,7 +298,6 @@ loadEntityFunction(const char *url, const char *eid, xmlParserCtxtPtr *ctxt); * [d setRoot: [d makeNodeWithNamespace: nil name: @"plist" content: nil]]; * [[d root] setProp: @"version" value: @"0.9"]; * n1 = [[d root] makeChildWithNamespace: nil name: @"dict" content: nil]; - * * */ - (GSXMLNode*) makeNodeWithNamespace: (GSXMLNamespace*)ns @@ -1366,7 +1375,6 @@ static NSMapTable *attrNames = 0; * while ((a = [a next]) != nil) * { * NSLog(@"n1 property name - %@ value - %@", [a name], [a value]); * } - * * */ - (GSXMLAttribute*) next