Documentation work.

8 files changed, 121 insertions, 87 deletions

diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi
index d54bce22..b122fdfd 100644
--- a/doc/ref/calp.texi
+++ b/doc/ref/calp.texi
@@ -73,6 +73,7 @@ text @footnote{Improvements welcome}
 @include text.texi
 @include vulgar.texi
 @include introspection.texi
+@include object.texi
 
 @node Index
 @unnumbered Index
diff --git a/doc/ref/general.texi b/doc/ref/general.texi
index a2fc2ca3..1810a29b 100644
--- a/doc/ref/general.texi
+++ b/doc/ref/general.texi
@@ -22,8 +22,8 @@ of these should be generally useful in any project.
 @include general/graph.texi
 @include general/options.texi
 
+@c TODO document (hnh util coverage)
 
 @include general/util-type.texi
-@include general/util-object.texi
 @include general/lens.texi
 @include general/sxml.texi
diff --git a/doc/ref/general/io.texi b/doc/ref/general/io.texi
index 178df749..e7ff51fa 100644
--- a/doc/ref/general/io.texi
+++ b/doc/ref/general/io.texi
@@ -10,6 +10,8 @@ Like @code{open-*-file}, but ``-'' gives @code{standard-@{input,output@}}.
 
 @defun read-lines port
 Return a list of all lines read from port.
+
+The trailing newlines are @emph{not} part of the string.
 @end defun
 
 @defun with-atomic-output-to-file filename thunk
diff --git a/doc/ref/general/lens.texi b/doc/ref/general/lens.texi
index e59b5d72..a07dd7c9 100644
--- a/doc/ref/general/lens.texi
+++ b/doc/ref/general/lens.texi
@@ -3,6 +3,8 @@
 
 Provided by the module @code{(hnh util lens)}
 
+@c TODO write an actuall introduction here
+
 @defun modify object lens f args ...
 @end defun
 
diff --git a/doc/ref/general/util-object.texi b/doc/ref/general/util-object.texi
deleted file mode 100644
index ceac2f2a..00000000
--- a/doc/ref/general/util-object.texi
+++ /dev/null
@@ -1,86 +0,0 @@
-@node define-type
-@section Yet Another Object System
-
-@defmac define-type (name type-parameters ...) fields ...
-Introduce a new type.
-
-Each field is either a symbol, or a list where the first element is a
-symbol, and the remaining elements are alternating keywords and
-values, as per @ref{Field Parameters}. All fields are optional by
-default, but can be made non-optional through its type parameter.
-
-The example below creates a new type called @var{type}, with a custom
-printer which always displays the string ``TYPE''. It has two fields,
-@var{x}, which must be an integer, and @var{y}, which can have any
-type, but gets the value ``Hello'' in none is given.
-@example
-(define-type (type #:printer (lambda (r p) (display "TYPE" p)))
-  (x #:type integer?)
-  (y #:default "Hello"))
-@end example
-@end defmac
-
-@subsection Type Parameters
-
-@deffn {Type Parameter} constructor (λ (primitive-constructor type-validator))
-Use a custom constructor for the type. The given procedure is called
-with two values:
-@itemize
-@item the types primitive (and usually hidden) constructor,
-which takes as many arguments as there are fields, in the order given
-in define-type, and
-@item the type validator procedure, which also takes all arguments,
-but instead either returns an undefined value if everything is fine,
-or throws @code{'wrong-type-arg} otherwise.
-@end itemize
-The procedure should then return a new procedure, which will be bound
-as the constructor for the type. Note that default values are current
-disregarded with custom constructors.
-
-A custom constructor for the type above might look like
-@example
-(lambda (primitive-constructor type-check)
-  (lambda* (#:key x y)
-    (type-check x y)
-    (primitive-constructor x y)))
-@end example
-@end deffn
-
-@deffn {Type Parameter} printer (λ (record port))
-Use a custom printer for the type.
-@end deffn
-
-@subsection Field Parameters
-@anchor{Field Parameters}
-
-@deffn {Field Parameter} default value
-Value the field should get if not given.
-@end deffn
-
-@deffn {Field Parameter} type type-clause
-A type predicate that the field must obey. See @ref{type-clause} for details.
-@end deffn
-
-@subsection Introduced Bindings
-
-Define type introduces a number procedures. (@var{<name>} should be
-replaced with whatever was given as @var{name} to define-type.
-
-@defun @var{<name>} [kv-args ...]
-Type constructor. Takes key-value arguments. Where the keys are the
-names of the fields.
-@end defun
-
-@defun @var{<name>}? x
-Type predicate.
-@end defun
-
-And for each field @var{<field>}:
-
-@defun @var{<field>} object [value]
-Accessor for the given filed.
-Returns the current value if called with only an object, and returns a
-new object with @var{field} set to @var{value} if called with two values.
-
-The updating version checks the type if #:type was given on creation.
-@end defun
diff --git a/doc/ref/general/util.texi b/doc/ref/general/util.texi
index 1d6a4e7a..ced5c27a 100644
--- a/doc/ref/general/util.texi
+++ b/doc/ref/general/util.texi
@@ -341,6 +341,13 @@ A variable can also be removed from the environment, by setting its
 value to @code{#f}.
 @end defmac
 
+@defmac with-working-directory directory thunk
+Run @var{thunk} with the working directory set to @var{directory}.
+
+Note that this probably isn't thread safe. See source for more
+inforamtion.
+@end defmac
+
 @defmac with-locale1 category locale thunk
 Run @var{thunk} with the locale @var{category} temporarily set to
 @var{locale}.
diff --git a/doc/ref/object.texi b/doc/ref/object.texi
new file mode 100644
index 00000000..8fa2e1e9
--- /dev/null
+++ b/doc/ref/object.texi
@@ -0,0 +1,4 @@
+@node Yet Another Object System
+@chapter Yet Another Object System
+
+@include object/object.texi
diff --git a/doc/ref/object/object.texi b/doc/ref/object/object.texi
new file mode 100644
index 00000000..7eff8ec2
--- /dev/null
+++ b/doc/ref/object/object.texi
@@ -0,0 +1,104 @@
+@node YAOS Primitives
+@section Primitives
+
+What Scheme lacks is a proper object system. This library solves that
+problem @emph{once and for all}!
+
+The records created through this library are all immutale, where each
+field becomes a multiple dispatch procedure, whence called with a
+single argument returns the value of that field, and when called with
+two values (first one being the object, second being the new value)
+returns a new instance of the object, with the field in question
+replaced.
+
+@defmac define-type (name type-parameters ...) fields ...
+Introduce a new type, disjoint from all previously defined types.
+
+@c Each field is either a symbol, or a list where the first element is a
+@c symbol, and the remaining elements are alternating keywords and
+@c values, as per @ref{Field Parameters}. All fields are optional by
+@c default, but can be made non-optional through its type parameter.
+
+@c The example below creates a new type called @var{type}, with a custom
+@c printer which always displays the string ``TYPE''. It has two fields,
+@c @var{x}, which must be an integer, and @var{y}, which can have any
+@c type, but gets the value ``Hello'' in none is given.
+@c @example
+@c (define-type (type #:printer (lambda (r p) (display "TYPE" p)))
+@c   (x #:type integer?)
+@c   (y #:default "Hello"))
+@c @end example
+
+@var{type-parameters} is a key-value list, where the valid keys are
+
+@deffn {Type Parameter} #:constructor (λ (primitive-constructor type-validator))
+The defaulct constructor for these types simply takes a keyword-value
+list, validates each argument in regard to the defined types, and
+constructs a final object. However; sometimes a more advanced
+constructor is needed, which can be added through this parameter.
+
+The custom constructor is called with two values:
+
+@itemize
+@item the types primitive (and usually hidden) constructor,
+which takes as many arguments as there are fields, in the order given
+in define-type, and
+@item the type validator procedure, which also takes all arguments,
+but instead either returns an undefined value if everything is fine,
+or throws @code{'wrong-type-arg} otherwise.
+@end itemize
+The procedure should then return a new procedure, which will be bound
+as the constructor for the type. Note that default values are current
+disregarded with custom constructors.
+
+A custom constructor for the type above might look like
+@example
+(lambda (primitive-constructor type-check)
+  (lambda* (#:key x y)
+    (type-check x y)
+    (primitive-constructor x y)))
+@end example
+@end deffn
+
+@deffn {Type Parameter} #:printer (λ (record port))
+Use a custom printer for the type.
+@end deffn
+
+Each field declares a part of the record, along with relevant metadata
+about that field. The most basic declaration is a bare symbol, which
+adds a field which can hold anything. However, a list with the target
+name as its first element can instead be given, with the tail
+containing keyword arguments as follows
+
+@deffn {Field Parameter} default value
+Value the field should get if not given.
+@end deffn
+
+@deffn {Field Parameter} type type-clause
+A type predicate that the field must obey. See @ref{type-clause} for details.
+
+Each type introduces a number of bindings, which are@footnote{
+@var{<name>} here refers to the name of the type
+}:
+@end deffn
+
+@defun @var{<name>} [kv-args ...]
+Type constructor. Takes key-value arguments. Where the keys are the
+names of the fields.
+@end defun
+
+@defun @var{<name>}? x
+Type predicate.
+@end defun
+
+And for each field @var{<field>}:
+
+@defun @var{<field>} object [value]
+Accessor for the given filed.
+Returns the current value if called with only an object, and returns a
+new object with @var{field} set to @var{value} if called with two values.
+
+The updating version checks the type if #:type was given on creation.
+@end defun
+
+@end defmac