-GUILE_PROC (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
- (SCM extra_fields, SCM tail_array_size, SCM init),
-"Return a new, self-describing vtable structure.
-
-@var{new-fields} is a layout specification describing fields
-of the resulting structure beginning at the position bound to
-@code{vtable-offset-user}.
-
-@var{tail-size} specifies the size of the tail-array (if any) of
-this vtable.
-
-@var{inits} initializes the fields of the vtable. Minimally, one
-initializer must be provided: the layout specification for instances
-of the type this vtable will describe. If a second initializer is
-provided, it will be interpreted as a print call-back function.
-
-@example
-;;; loading ,a...
-(define x
- (make-vtable-vtable (make-struct-layout (quote pw))
- 0
- 'foo))
-
-(struct? x)
-@result{} #t
-(struct-vtable? x)
-@result{} #t
-(eq? x (struct-vtable x))
-@result{} #t
-(struct-ref x vtable-offset-user)
-@result{} foo
-(struct-ref x 0)
-@result{} pruosrpwpw
-
-
-(define y
- (make-struct x
- 0
- (make-struct-layout (quote pwpwpw))
- 'bar))
-
-(struct? y)
-@result{} #t
-(struct-vtable? y)
-@result{} #t
-(eq? x y)
-@result{} ()
-(eq? x (struct-vtable y))
-@result{} #t
-(struct-ref y 0)
-@result{} pwpwpw
-(struct-ref y vtable-offset-user)
-@result{} bar
-
-
-(define z (make-struct y 0 'a 'b 'c))
-
-(struct? z)
-@result{} #t
-(struct-vtable? z)
-@result{} ()
-(eq? y (struct-vtable z))
-@result{} #t
-(map (lambda (n) (struct-ref z n)) '(0 1 2))
-@result{} (a b c)
-@end example
-")
+SCM_DEFINE (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
+ (SCM user_fields, SCM tail_array_size, SCM init),
+ "Return a new, self-describing vtable structure.\n\n"
+ "@var{user-fields} is a string describing user defined fields of the\n"
+ "vtable beginning at index @code{vtable-offset-user}\n"
+ "(see @code{make-struct-layout}).\n\n"
+ "@var{tail-size} specifies the size of the tail-array (if any) of\n"
+ "this vtable.\n\n"
+ "@var{init1}, @dots{} are the optional initializers for the fields of\n"
+ "the vtable.\n\n"
+ "Vtables have one initializable system field---the struct printer.\n"
+ "This field comes before the user fields in the initializers passed\n"
+ "to @code{make-vtable-vtable} and @code{make-struct}, and thus works as\n"
+ "a third optional argument to @code{make-vtable-vtable} and a fourth to\n"
+ "@code{make-struct} when creating vtables:\n\n"
+ "If the value is a procedure, it will be called instead of the standard\n"
+ "printer whenever a struct described by this vtable is printed.\n"
+ "The procedure will be called with arguments STRUCT and PORT.\n\n"
+ "The structure of a struct is described by a vtable, so the vtable is\n"
+ "in essence the type of the struct. The vtable is itself a struct with\n"
+ "a vtable. This could go on forever if it weren't for the\n"
+ "vtable-vtables which are self-describing vtables, and thus terminate\n"
+ "the chain.\n\n"
+ "There are several potential ways of using structs, but the standard\n"
+ "one is to use three kinds of structs, together building up a type\n"
+ "sub-system: one vtable-vtable working as the root and one or several\n"
+ "\"types\", each with a set of \"instances\". (The vtable-vtable should be\n"
+ "compared to the class <class> which is the class of itself.)\n\n"
+ "@lisp\n"
+ "(define ball-root (make-vtable-vtable \"pr\" 0))\n\n"
+ "(define (make-ball-type ball-color)\n"
+ " (make-struct ball-root 0\n"
+ " (make-struct-layout \"pw\")\n"
+ " (lambda (ball port)\n"
+ " (format port \"#<a ~A ball owned by ~A>\"\n"
+ " (color ball)\n"
+ " (owner ball)))\n"
+ " ball-color))\n"
+ "(define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))\n"
+ "(define (owner ball) (struct-ref ball 0))\n\n"
+ "(define red (make-ball-type 'red))\n"
+ "(define green (make-ball-type 'green))\n\n"
+ "(define (make-ball type owner) (make-struct type 0 owner))\n\n"
+ "(define ball (make-ball green 'Nisse))\n"
+ "ball @result{} #<a green ball owned by Nisse>\n"
+ "@end lisp")