Fixing README

Göran Krampe
1 parent 70473583
Showing 1 changed file with 45 additions and 51 deletions
README.md
@@ -28,7 +28,7 @@ How do I use it?
 Example: 
 ```
-  system: aString
+system: aString
   "Some kind of comment"
 	<apicall: long 'system' (char*) module: 'libSystem.dylib'>
@@ -42,31 +42,29 @@ Then comes the so called pragma that describes the C function to call:
 ```
 	<apicall: long 'system' (char*) module: 'libSystem.dylib'>
 ```
-Function specification:
-	- should be the first line in the method
-	- enclosed in angle brackets: < > containing:
-		1. Calling Convention, either apicall: (Pascal convention) or cdecl: (C convention)
-			- Mac - use either one
-			- Unix - use cdecl
-			- Windows - use apical
-		2. Return Type (see types)
-		3. External Function Name (literal string)
-		4. Argument Types (a literal array)
-		5. Module - "module: " + [filename of the external library (literal string)] (see below).
+Function specification should be the first line in the method and enclosed in angle brackets: < > containing:
+1. Calling Convention, either apicall: (Pascal convention) or cdecl: (C convention)
+	- Mac - use either one
+	- Unix - use cdecl
+	- Windows - use apical
+2. Return Type (see types)
+3. External Function Name (literal string)
+4. Argument Types (a literal array)
+5. Module - "module: " + [filename of the external library (literal string)] (see below).
 ```
 	^self externalCallFailed.
 ```
-Failure handler
-	- normal smalltalk code
-	- executed if the linking to or calling the external function fails
-	- API calls don't know how to communicate failure like Squeak primitives do, so:
-		- it does not tell you whether the external function succeeded
-		- the most common code is simply '^self externalCallFailed.'
+Failure handler:
-Argument Types
-	- must be names of ExternalTypes, either:
+* normal smalltalk code
+* executed if the linking to or calling the external function fails
+* API calls don't know how to communicate failure like Squeak primitives do, so:
+  * it does not tell you whether the external function succeeded
+  * the most common code is simply '^self externalCallFailed.'
+
+Argument Types must be names of ExternalTypes, either:
 		- atomic types (see ExternalType class>>initializeFFIConstants and ExternalType class>>initializeAtomicTypes):
 			void
 			bool
@@ -84,19 +82,17 @@ Argument Types
 			double (double-precision float)
 Structure Types [4]
-	- subclass of ExternalStructure
-		- class>>fields that returns an array of field descriptions (see below)
-			- Example:
-				fields
-					^#((red   'byte')(green 'byte')(blue  'byte'))           
-		- class>>initialize which includes "self defineFields" (which must be
-called before using the class)
-	- refer to as MyExternalStructure* (to indicate that the argument or return is a pointer to that structure)
+* subclass of ExternalStructure
+* class>>fields that returns an array of field descriptions (see below), example:
+			fields
+				^#((red   'byte')(green 'byte')(blue  'byte'))           
+* class>>initialize which includes "self defineFields" (which must be called before using the class)
+* refer to as MyExternalStructure* (to indicate that the argument or return is a pointer to that structure)
 Field description [4]
-	- 2-element array (or three but that does something else, I'm not sure what):
-		- first element is the field name
-		- second is the type
+* 2-element array (or three but that does something else, I'm not sure what):
+	* first element is the field name
+	* second is the type
 Module Name 
 - depends on the platform
@@ -108,29 +104,27 @@ Module Name
 			- For Classic applications, use 'InterfaceLib'
 			- For Carbon libs, use 'CarbonLib'
-Module Location - where the external library file lives
-	- depends on the platform
-		- Mac
-			- pre Snow Leopard
-				- checks VM path and common library paths
-			- Snow Leopard
-				- only looks in VM bundle's Resources file, you must either [5]:
-					- store all external libraries there
-					- ln -s path/to/library path/to/VM/Resources/library_name
-					- Change the VM's Info.plist "SqueakPluginsBuiltInOrLocalOnly" key from "true" to "false."
+Module Location, where the external library file lives
+- depends on the platform
+	- Mac
+		- pre Snow Leopard
+			- checks VM path and common library paths
+		- Snow Leopard
+			- only looks in VM bundle's Resources file, you must either [5]:
+				- store all external libraries there
+				- ln -s path/to/library path/to/VM/Resources/library_name
+				- Change the VM's Info.plist "SqueakPluginsBuiltInOrLocalOnly" key from "true" to "false."
 Caveats
-	- security
-		- malicious users could call arbitrary functions in the OS e.g.  "format c:" from "system.dll" [7]
-		- VMs do not protect against buffer overflow from bad parameters [8]:
-			"this would require an attacker to execute arbitrary Smalltalk 
-			code on your server. Of course if they can do that they own you 
-			anyway, especially if you allow FFi or use the OSProcess plugin" - John McIntosh
+- security
+	- malicious users could call arbitrary functions in the OS e.g.  "format c:" from "system.dll" [7]
+	- VMs do not protect against buffer overflow from bad parameters [8]:
+		"this would require an attacker to execute arbitrary Smalltalk 
+		code on your server. Of course if they can do that they own you 
+		anyway, especially if you allow FFi or use the OSProcess plugin" - John McIntosh
 * difficulty
-	- if you make a mistake you'll not drop into the debugger but Squeak will
-just crash [2]
-	- If you crash Squeak when it is running the garbage collector, then you
-know your FFI code is leaking bits into object memory [2]
+	- if you make a mistake you'll not drop into the debugger but Squeak will just crash [2]
+	- If you crash Squeak when it is running the garbage collector, then you know your FFI code is leaking bits into object memory [2]
 What do I need to use FFI with Squeak?