Comment out (w/ "@c essay " prefix) portions

required for stand-alone processing.

doc/data-rep.texi

@@ -1,84 +1,83 @@
-\input texinfo
+@c essay \input texinfo
-@c -*-texinfo-*-
+@c essay @c -*-texinfo-*-
-@c %**start of header
+@c essay @c %**start of header
-@setfilename data-rep.info
+@c essay @setfilename data-rep.info
-@settitle Data Representation in Guile
+@c essay @settitle Data Representation in Guile
-@c %**end of header
+@c essay @c %**end of header
+@c essay
+@c essay @include version.texi
+@c essay
+@c essay @dircategory The Algorithmic Language Scheme
+@c essay @direntry
+@c essay * data-rep: (data-rep).  Data Representation in Guile --- how to use
+@c essay                          Guile objects in your C code.
+@c essay @end direntry
+@c essay
+@c essay @setchapternewpage off
+@c essay
+@c essay @ifinfo
+@c essay Data Representation in Guile
+@c essay
+@c essay Copyright (C) 1998, 1999, 2000 Free Software Foundation
+@c essay
+@c essay Permission is granted to make and distribute verbatim copies of
+@c essay this manual provided the copyright notice and this permission notice
+@c essay are preserved on all copies.
+@c essay
+@c essay @ignore
+@c essay Permission is granted to process this file through TeX and print the
+@c essay results, provided the printed document carries copying permission
+@c essay notice identical to this one except for the removal of this paragraph
+@c essay (this paragraph not being relevant to the printed manual).
+@c essay @end ignore
+@c essay
+@c essay Permission is granted to copy and distribute modified versions of this
+@c essay manual under the conditions for verbatim copying, provided that the entire
+@c essay resulting derived work is distributed under the terms of a permission
+@c essay notice identical to this one.
+@c essay
+@c essay Permission is granted to copy and distribute translations of this manual
+@c essay into another language, under the above conditions for modified versions,
+@c essay except that this permission notice may be stated in a translation approved
+@c essay by the Free Software Foundation.
+@c essay @end ifinfo
+@c essay
+@c essay @titlepage
+@c essay @sp 10
+@c essay @comment The title is printed in a large font.
+@c essay @title Data Representation in Guile
+@c essay @subtitle $Id: data-rep.texi,v 1.11.2.1 2002-05-05 11:29:56 ttn Exp $
+@c essay @subtitle For use with Guile @value{VERSION}
+@c essay @author Jim Blandy
+@c essay @author Free Software Foundation
+@c essay @author @email{jimb@@red-bean.com}
+@c essay @c The following two commands start the copyright page.
+@c essay @page
+@c essay @vskip 0pt plus 1filll
+@c essay @vskip 0pt plus 1filll
+@c essay Copyright @copyright{} 1998 Free Software Foundation
+@c essay
+@c essay Permission is granted to make and distribute verbatim copies of
+@c essay this manual provided the copyright notice and this permission notice
+@c essay are preserved on all copies.
+@c essay
+@c essay Permission is granted to copy and distribute modified versions of this
+@c essay manual under the conditions for verbatim copying, provided that the entire
+@c essay resulting derived work is distributed under the terms of a permission
+@c essay notice identical to this one.
+@c essay
+@c essay Permission is granted to copy and distribute translations of this manual
+@c essay into another language, under the above conditions for modified versions,
+@c essay except that this permission notice may be stated in a translation approved
+@c essay by Free Software Foundation.
+@c essay @end titlepage
+@c essay
+@c essay @c @smallbook
+@c essay @c @finalout
+@c essay @headings double
 
-@include version.texi
+@node Data Representation
-
+@chapter Data Representation
-@dircategory The Algorithmic Language Scheme
-@direntry
-* data-rep: (data-rep).  Data Representation in Guile --- how to use
-                         Guile objects in your C code.
-@end direntry
-
-@setchapternewpage off
-
-@ifinfo
-Data Representation in Guile
-
-Copyright (C) 1998, 1999, 2000 Free Software Foundation
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-@end ignore
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Free Software Foundation.
-@end ifinfo
-
-@titlepage
-@sp 10
-@comment The title is printed in a large font.
-@title Data Representation in Guile
-@subtitle $Id: data-rep.texi,v 1.11 2000-06-20 03:22:56 mdj Exp $
-@subtitle For use with Guile @value{VERSION}
-@author Jim Blandy
-@author Free Software Foundation
-@author @email{jimb@@red-bean.com}
-@c The following two commands start the copyright page.
-@page
-@vskip 0pt plus 1filll
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1998 Free Software Foundation
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by Free Software Foundation.
-@end titlepage
-
-@c @smallbook
-@c @finalout
-@headings double
-
-
-@node Top, Data Representation in Scheme, (dir), (dir)
-@top Data Representation in Guile
 
 @ifinfo
 This essay is meant to provide the background necessary to read and
@@ -93,7 +92,7 @@ actually represents Scheme values.  Otherwise, a lot of the code, and
 the conventions it follows, won't make very much sense.
 
 We assume you know both C and Scheme, but we do not assume you are
-familiar with Guile's C interface.
+familiar with Guile's implementation.
 @end ifinfo
 
 @menu
@@ -106,7 +105,7 @@ familiar with Guile's C interface.
                                         application-specific datatypes.
 @end menu
 
-@node Data Representation in Scheme, How Guile does it, Top, Top
+@node Data Representation in Scheme
 @section Data Representation in Scheme
 
 Scheme is a latently-typed language; this means that the system cannot,
@@ -143,7 +142,7 @@ does it}.
 * Guile Is Hairier::
 @end menu
 
-@node A Simple Representation, Faster Integers, Data Representation in Scheme, Data Representation in Scheme
+@node A Simple Representation
 @subsection A Simple Representation
 
 The simplest way to meet the above requirements in C would be to
@@ -187,7 +186,7 @@ semantics.  If @var{x} is an @code{SCM} value:
 @end itemize
 
 
-@node Faster Integers, Cheaper Pairs, A Simple Representation, Data Representation in Scheme
+@node Faster Integers
 @subsection Faster Integers
 
 Unfortunately, the above representation has a serious disadvantage.  In
@@ -282,7 +281,7 @@ but this essay isn't about bit-twiddling.  (Hint: what if pointers had
 @code{01} in their least significant bits, and integers had @code{00}?)
 
 
-@node Cheaper Pairs, Guile Is Hairier, Faster Integers, Data Representation in Scheme
+@node Cheaper Pairs
 @subsection Cheaper Pairs
 
 However, there is yet another issue to confront.  Most Scheme heaps
@@ -380,7 +379,7 @@ are referencing, making a modified pointer as fast to use as an
 unmodified pointer.
 
 
-@node Guile Is Hairier,  , Cheaper Pairs, Data Representation in Scheme
+@node Guile Is Hairier
 @subsection Guile Is Hairier
 
 We originally started with a very simple typing system --- each object
@@ -396,7 +395,7 @@ significant loss of efficiency, but the simplified system would still be
 more complex than what we've presented above.
 
 
-@node How Guile does it, Defining New Types (Smobs), Data Representation in Scheme, Top
+@node How Guile does it
 @section How Guile does it
 
 Here we present the specifics of how Guile represents its data.  We
@@ -415,7 +414,7 @@ everything one need know to use Guile's data.
 * Signalling Type Errors::
 @end menu
 
-@node General Rules, Garbage Collection, How Guile does it, How Guile does it
+@node General Rules
 @subsection General Rules
 
 Any code which operates on Guile datatypes must @code{#include} the
@@ -446,7 +445,7 @@ boolean value have names starting with @code{SCM_N}.  For example,
 @emph{not} a pair object (a @code{CONS}).
 
 
-@node Garbage Collection, Immediates vs. Non-immediates, General Rules, How Guile does it
+@node Garbage Collection
 @subsection Garbage Collection
 
 Aside from the latent typing, the major source of constraints on a
@@ -530,7 +529,7 @@ many pieces of code, it is enough for the collector to find the cell,
 and then use the cell's type to find more pointers to trace.
 
 
-@node Immediates vs. Non-immediates, Immediate Datatypes, Garbage Collection, How Guile does it
+@node Immediates vs. Non-immediates
 @subsection Immediates vs. Non-immediates
 
 Guile classifies Scheme objects into two kinds: those that fit entirely
@@ -571,7 +570,7 @@ from this weakness.
 @end deftypefn
 
 
-@node Immediate Datatypes, Non-immediate Datatypes, Immediates vs. Non-immediates, How Guile does it
+@node Immediate Datatypes
 @subsection Immediate Datatypes
 
 The following datatypes are immediate values; that is, they fit entirely
@@ -594,7 +593,7 @@ before applying them.
 * Unique Values::
 @end menu
 
-@node Integers, Characters, Immediate Datatypes, Immediate Datatypes
+@node Integers
 @subsubsection Integers
 
 Here are functions for operating on small integers, that fit within an
@@ -627,7 +626,7 @@ This function does not check for overflow.
 @end deftypefn
 
 
-@node Characters, Booleans, Integers, Immediate Datatypes
+@node Characters
 @subsubsection Characters
 
 Here are functions for operating on characters.
@@ -647,7 +646,7 @@ character value.
 @end deftypefn
 
 
-@node Booleans, Unique Values, Characters, Immediate Datatypes
+@node Booleans
 @subsubsection Booleans
 
 Here are functions and macros for operating on booleans.
@@ -670,7 +669,7 @@ Scheme boolean, the result is undefined.
 @end deftypefn
 
 
-@node Unique Values,  , Booleans, Immediate Datatypes
+@node Unique Values
 @subsubsection Unique Values
 
 The immediate values that are neither small integers, characters, nor
@@ -715,7 +714,7 @@ symbol's value to see if it has a binding as a global variable.
 @end deftypefn
 
 
-@node Non-immediate Datatypes, Signalling Type Errors, Immediate Datatypes, How Guile does it
+@node Non-immediate Datatypes
 @subsection Non-immediate Datatypes
 
 A non-immediate datatype is one which lives in the heap, either because
@@ -746,7 +745,7 @@ corrupted.
 * Ports::
 @end menu
 
-@node Non-immediate Type Predicates, Pairs, Non-immediate Datatypes, Non-immediate Datatypes
+@node Non-immediate Type Predicates
 @subsubsection Non-immediate Type Predicates
 
 As mentioned in @ref{Garbage Collection}, all non-immediate objects
@@ -767,7 +766,7 @@ SCM_NIMP (@var{x}) && SCM_CONSP (@var{x})
 @end example
 
 
-@node Pairs, Vectors, Non-immediate Type Predicates, Non-immediate Datatypes
+@node Pairs
 @subsubsection Pairs
 
 Pairs are the essential building block of list structure in Scheme.  A
@@ -852,7 +851,7 @@ Return the @sc{car} of the @sc{car} of @var{cell}, the @sc{car} of the
 @end deftypefn
 
 
-@node Vectors, Procedures, Pairs, Non-immediate Datatypes
+@node Vectors
 @subsubsection Vectors, Strings, and Symbols
 
 Vectors, strings, and symbols have some properties in common.  They all
@@ -899,7 +898,7 @@ There are also a few magic values stuffed into memory before a symbol's
 characters, but you don't want to know about those.  What cruft!
 
 
-@node Procedures, Closures, Vectors, Non-immediate Datatypes
+@node Procedures
 @subsubsection Procedures
 
 Guile provides two kinds of procedures: @dfn{closures}, which are the
@@ -916,7 +915,7 @@ any sort.  Otherwise, return @code{SCM_BOOL_F}.
 @end deftypefun
 
 
-@node Closures, Subrs, Procedures, Non-immediate Datatypes
+@node Closures
 @subsubsection Closures
 
 [FIXME: this needs to be further subbed, but texinfo has no subsubsub]
@@ -965,7 +964,7 @@ connected with the interpreter's implementation.
 @end deftypefn
 
 
-@node Subrs, Ports, Closures, Non-immediate Datatypes
+@node Subrs
 @subsubsection Subrs
 
 [FIXME: this needs to be further subbed, but texinfo has no subsubsub]
@@ -1016,13 +1015,13 @@ object instead of a subr object.
 @end deftypefun
 
 
-@node Ports,  , Subrs, Non-immediate Datatypes
+@node Ports
 @subsubsection Ports
 
 Haven't written this yet, 'cos I don't understand ports yet.
 
 
-@node Signalling Type Errors,  , Non-immediate Datatypes, How Guile does it
+@node Signalling Type Errors
 @subsection Signalling Type Errors
 
 Every function visible at the Scheme level should aggressively check the
@@ -1083,7 +1082,7 @@ Signal an error complaining that @var{obj} is ``out of range'' for
 @end deftypefn
 
 
-@node Defining New Types (Smobs),  , How Guile does it, Top
+@node Defining New Types (Smobs)
 @section Defining New Types (Smobs)
 
 @dfn{Smobs} are Guile's mechanism for adding new non-immediate types to
@@ -1113,7 +1112,7 @@ datatypes described here.)
 * A Complete Example::
 @end menu
 
-@node Describing a New Type, Creating Instances, Defining New Types (Smobs), Defining New Types (Smobs)
+@node Describing a New Type
 @subsection Describing a New Type
 
 To define a new type, the programmer must write four functions to
@@ -1236,7 +1235,7 @@ init_image_type ()
 @end example
 
 
-@node Creating Instances, Typechecking, Describing a New Type, Defining New Types (Smobs)
+@node Creating Instances
 @subsection Creating Instances
 
 Like other non-immediate types, smobs start with a cell whose @sc{car}
@@ -1349,7 +1348,7 @@ make_image (SCM name, SCM s_width, SCM s_height)
 @end example
 
 
-@node Typechecking, Garbage Collecting Smobs, Creating Instances, Defining New Types (Smobs)
+@node Typechecking
 @subsection Typechecking
 
 Functions that operate on smobs should aggressively check the types of
@@ -1401,9 +1400,7 @@ Note that checking types is a little more complicated during garbage
 collection; see the description of @code{SCM_GCTYP16} in @ref{Garbage
 Collecting Smobs}.
 
-@c GJB:FIXME:: should talk about guile-snarf somewhere!
+@node Garbage Collecting Smobs
-
-@node Garbage Collecting Smobs, A Common Mistake In Allocating Smobs, Typechecking, Defining New Types (Smobs)
 @subsection Garbage Collecting Smobs
 
 Once a smob has been released to the tender mercies of the Scheme
@@ -1544,7 +1541,7 @@ very simple.  Since collections occur at unpredictable times, it is easy
 for any unusual activity to interfere with normal code.
 
 
-@node A Common Mistake In Allocating Smobs, Garbage Collecting Simple Smobs, Garbage Collecting Smobs, Defining New Types (Smobs)
+@node A Common Mistake In Allocating Smobs
 @subsection A Common Mistake In Allocating Smobs
 
 When constructing new objects, you must be careful that the garbage
@@ -1616,7 +1613,7 @@ traverse @code{image}, so any objects @code{image} points to will be
 preserved.
 
 
-@node Garbage Collecting Simple Smobs, A Complete Example, A Common Mistake In Allocating Smobs, Defining New Types (Smobs)
+@node Garbage Collecting Simple Smobs
 @subsection Garbage Collecting Simple Smobs
 
 It is often useful to define very simple smob types --- smobs which have
@@ -1644,7 +1641,7 @@ other than the smob's header cell.
 @end deftypefun
 
 
-@node A Complete Example,  , Garbage Collecting Simple Smobs, Defining New Types (Smobs)
+@node A Complete Example
 @subsection A Complete Example
 
 Here is the complete text of the implementation of the image datatype,
@@ -1800,4 +1797,4 @@ Type "(backtrace)" to get more information.
 guile>
 @end example
 
-@bye
+@c essay @bye