g-wrap: reference manual updated

* g-wrap: reference manual updated
@ 2014-06-23  8:52 David Pirotte
       [not found] ` <874mzbn76m.fsf@gnu.org>
  0 siblings, 1 reply; 2+ messages in thread
From: David Pirotte @ 2014-06-23  8:52 UTC (permalink / raw)
  To: guile-devel


[-- Attachment #1.1: Type: text/plain, Size: 828 bytes --]

Hello guilers,

	g-wrap
	  master: reference manual updated

it all started because I wanted to get acces to modern procedure and type/class
indexes, as produced by texinfo 5.2.  then I realized that, appart from having to
solve raised bugs compiling with texinfo 5.2, it really could live with a serious
lifting :).  I did my best to improve the presentation and access to the great
material the previous g-wrap manual already had, mainly by restructuring it: it is
now almost identical, in structure, to the guile reference manual.

i would be happy to push this patch and also do the house keeping of the website so
that online html manual pages are actualized, if it's fine, give me write access
[savannah group request pending already].

of course review and comments are welcome.

Happu hacking,
David

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-g-wrap-reference-manual-updated-for-texinfo-5.2.patch --]
[-- Type: text/x-patch, Size: 69310 bytes --]

From 17effcf27930a1a43cbcbdf5a9ee522c9a2a1bee Mon Sep 17 00:00:00 2001
From: David PIROTTE <david@altosw.be>
Date: Mon, 23 Jun 2014 05:40:46 -0300
Subject: [PATCH] g-wrap reference manual updated for texinfo 5.2

Note: it all started because I wanted to get acces to modern procedure
and type/class indexes, as produced by texinfo 5.2.  then I realized
that, appart from having to solve raised bugs compiling with texinfo
5.2, it really could live with a serious lifting :).  I did my best to
improve the presentation and access to the great material the previous
g-wrap manual already had, mainly by restructuring it: it is now
almost identical, in structure, to the guile reference manual.

It is not easy to describe all these modifications in a few words, but
I can try :).

The top level [g-wrap.texi] document now only specify the license
extract dealing with the documentation itself.

The detailed-menu has been completely removed.

A Preface [non numbered] chapter has been added with 2 sections:
'Contributors to this manual' and 'The G-wrap License'.

The previous 'Overview' introduction section text has been moved and
is now the introduction text itself, preceeded by the first sentence
of the README file: it really is much clearer this way, I think.

'Why Create a Wrapper Generator?' becomes the first Introduction
chaper section. It is followed by 'Obtaining and Installing G-wrap' a
section which is new, and ends with the 'A simple example' section.

'Usage' [chapter] has been renamed 'A more detailed example', with its
text being what was precisly named 'A more detailed example' in the
previous version of this manual. The following 2 sections are
unchanged. 'The aggregated Type Qualifier' section has been added [the
original text was there but unused somehow]. This chaper now ends with
a new section which is 'Reporting bugs'.

The 'API Reference' chapter is unchanged.

Appendix 'A GNU Free Documentation License' added.  'Procedure and
Method Index' now precceeds the 'Type and Class Index', as for the
guile reference manual.

* doc/aggregate.texi:
* doc/effective-version.texi:
* doc/fdl.texi:
* doc/install.texi:
* doc/preface.texi:
* doc/report-bugs.texi:
* doc/version.texi: added

* doc/g-wrap.texi: modified as described above.
---
 doc/aggregate.texi         |  96 ++++++++
 doc/effective-version.texi |   1 +
 doc/fdl.texi               | 506 +++++++++++++++++++++++++++++++++++++++++
 doc/g-wrap.texi            | 545 ++++++++++++++++++---------------------------
 doc/install.texi           |  41 ++++
 doc/preface.texi           |  63 ++++++
 doc/report-bugs.texi       |  61 +++++
 doc/version.texi           |   4 +
 8 files changed, 992 insertions(+), 325 deletions(-)
 create mode 100644 doc/aggregate.texi
 create mode 100644 doc/effective-version.texi
 create mode 100644 doc/fdl.texi
 create mode 100644 doc/install.texi
 create mode 100644 doc/preface.texi
 create mode 100644 doc/report-bugs.texi
 create mode 100644 doc/version.texi

diff --git a/doc/aggregate.texi b/doc/aggregate.texi
new file mode 100644
index 0000000..6c3339f
--- /dev/null
+++ b/doc/aggregate.texi
@@ -0,0 +1,96 @@
+@c -*-texinfo-*-
+@c This is part of the G-Wrap Reference Manual.
+@c Copyright (C)  2014 David Pirotte
+@c See the file g-wrap.texi for copying conditions.
+
+@node The @code{aggregated} Type Qualifier
+@section The @code{aggregated} Type Qualifier
+
+@cindex memory management
+@cindex aggregated object
+@cindex constructor
+The @code{aggregated} type qualifier is mostly useful when wrapping C
+functions (constructors) that return a new object which aggregates
+objects passed as its input parameters.  In order to illustrate the
+need for this typespec, let's imagine the following C API:
+
+@smallexample
+/* Return a new stuff.  */
+stuff_t *make_stuff (void);
+
+/* Return a stuff container that contains a pointer to CONTAINED.
+   Note that the container returned is _not_ responsible for
+   deallocating the resources attached to CONTAINED.  */
+stuff_container_t *make_stuff_container (stuff_t *contained);
+@end smallexample
+
+And now, imagine the following Scheme code that uses bindings of the
+above functions:
+
+@smalllisp
+(define c (make-stuff-container (make-stuff)))
+@end smalllisp
+
+Suppose the two C types are wrapped as WCTs (@pxref{Wrapping a C
+Pointer Type}).  The call to @code{make-stuff} will create a new
+Scheme object (a WCP, or a ``SMOB'' in Guile terms, @pxref{Defining
+New Types (Smobs), SMOBs,, guile, The GNU Guile Reference Manual}) for
+the underlying C object.  However, as soon as
+@code{make-stuff-container} has returned, the Scheme code no longer
+holds any SMOB representing the value that was returned by
+@code{make-stuff}.  Consequently, the SMOB returned by
+@code{make-stuff} may soon be garbage-collected by Guile, and its
+underlying C object (originally returned by @code{make_stuff ()}) may
+soon get freed as well.
+
+But, here is the problem: the C @code{stuff_container_t} object still
+contains a pointer to that @code{stuff_t} object that has just been
+deleted!  The goal of the @code{aggregated} typespec is to solve
+situations like this one.  In the example above, the wrapped function
+and the container type should be specified as follows:
+
+@lisp
+(wrap-as-wct! ws
+              #:name '<stuff>
+              #:c-type-name "stuff_t *"
+              #:c-const-type-name "const stuff_t *"
+              #:allowed-options '(aggregated))
+
+...
+
+(wrap-function! ws
+                #:name 'make-stuff-container
+                #:c-name "make_stuff_container"
+                #:returns '<stuff-container>
+                #:arguments '(((<stuff> aggregated) stuff)))
+@end lisp
+
+Literally, this means: ``the argument @var{stuff} of
+@code{make-stuff-container} is @emph{aggregated} by the object
+returned by @code{make-stuff-container}; therefore, it may not be GC'd
+unless the object returned by @code{make-stuff-container} is GC'd
+too.''
+
+@cindex finalization order
+Additionally, G-Wrap, in this case, enforces the @emph{finalization
+order} of WCPs: even if both the referrer (the
+@code{<stuff-container>} object) and its dependency (the @var{stuff}
+argument) become unreachable during the same GC phase, G-Wrap makes
+sure that their @code{wcp-free-function}s (@pxref{Wrapping a C Pointer
+Type}) are called in the right order, i.e., referrer first, dependency
+second.
+
+@cindex reference counting
+Note that some libraries, such as GTK+, solve this problem by relying
+on reference counting: aggregating objects must increment the
+reference counter of the objects they refer to.  The @code{aggregated}
+type qualifier facility can be seen as a solution for those C
+libraries that do @emph{not} use reference counting but have memory
+ownership semantics similar to the ones described above.  An example
+of such a library is Berkeley DB.
+
+
+@c Local Variables:
+@c TeX-master: "g-wrap.texi"
+@c ispell-local-dictionary: "american"
+@c End:
diff --git a/doc/effective-version.texi b/doc/effective-version.texi
new file mode 100644
index 0000000..d30a6f6
--- /dev/null
+++ b/doc/effective-version.texi
@@ -0,0 +1 @@
+@set EFFECTIVE-VERSION 1.9.0
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644
index 0000000..8805f1a
--- /dev/null
+++ b/doc/fdl.texi
@@ -0,0 +1,506 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The ``Document'', below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as ``you''.  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject.  (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification.  Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
+@acronym{JPG}.  Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
+@acronym{XML} for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''.  You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.  If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.  A
+public wiki that anybody can edit is an example of such a server.  A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.3
+  or any later version published by the Free Software Foundation;
+  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.'' line with this:
+
+@smallexample
+@group
+    with the Invariant Sections being @var{list their titles}, with
+    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+    being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
diff --git a/doc/g-wrap.texi b/doc/g-wrap.texi
index dc8d708..abc95f0 100644
--- a/doc/g-wrap.texi
+++ b/doc/g-wrap.texi
@@ -1,17 +1,41 @@
-\input texinfo @c -*-texinfo-*-
+\input texinfo
+@c -*-texinfo-*-
 @c %**start of header
 @setfilename g-wrap.info
-@settitle G-Wrap
-@setchapternewpage on
-@c Choices for setchapternewpage are {on,off,odd}.
-@paragraphindent 0
+@documentencoding UTF-8
+@settitle G-Wrap Reference Manual
+@set g-wrap
+@set MANUAL-REVISION 1
 @c %**end of header
 
+@include version.texi
+@include effective-version.texi
+
+@copying
+This manual documents G-Wrap version @value{VERSION}.
+
+Copyright @copyright{} 1996-1998 Christopher Lee, 2000-2001 Rob
+Browning, 2004 Andreas Rottmann, 2005 Ludovic Courtès, 2006
+Christopher Lee, 2007 Ludovic Courtès, 2014 David Pirotte.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License.''
+@end copying
+
+
 @dircategory Libraries
 @direntry
-* G-Wrap: (g-wrap). Scheme wrapper for C libraries
+* G-Wrap Reference: (g-wrap).  Scheme wrapper for C libraries
 @end direntry
 
+@c Choices for setchapternewpage are {on,off,odd}.
+@setchapternewpage odd
+@c @paragraphindent 0
+
 @iftex
 @finalout
 @c DL: lose the egregious vertical whitespace, esp. around examples
@@ -20,149 +44,70 @@
 @end iftex
 
 @titlepage
-@title G-Wrap
+@sp 10
+@comment The title is printed in a large font.
+@title G-Wrap Reference Manual
 @subtitle A tool to wrap C APIs for Guile use.
-@subtitle Version 1.9.0
-@subtitle June 2004
+@subtitle Edition @value{EDITION}, revision @value{MANUAL-REVISION},
+for use with G-Wrap @value{VERSION}
 @author Christopher Lee <chrislee@@ri.cmu.edu>
 @author Rob Browning <rlb@@defaultvalue.org>
 @author Andreas Rottmann <rotty@@debian.org>
-@author Ludovic Court@`es <ludovic.courtes@@laas.fr>
+@author Ludovic Courtès <ludovic.courtes@@laas.fr>
+@author David Pirotte <david@@altosw.be>
 
+@c The following two commands start the copyright page.
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1996, 1997, 1998, 2006 Christopher Lee
-Copyright @copyright{} 2000-2001 Rob Browning
-Copyright @copyright{} 2004 Andreas Rottmann
-Copyright @copyright{} 2005, 2006, 2007 Ludovic Court@`es
-
-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 the author.
+@insertcopying
 @end titlepage
 
-@node Top, Copying, (dir), (dir)
-@ifinfo
-
-This is the info manual for G-Wrap, covering versions 1.9.*.
-
-@end ifinfo
-
-@menu
-* Copying::                     
-* Introduction::                
-* Usage::                       
-* API Reference::               
-* Concept Index::               
-* Type and Class Index::        
-* Procedure and Method Index::  
-
-@detailmenu
- --- The Detailed Node Listing ---
-
-Introduction
-
-* Overview::                    
-* Why Create a Wrapper Generator?::  
+@c @smallbook
+@finalout
+@headings double
 
-Usage
+@c Where to find G-Wrap examples.
+@set example-dir guile/examples
 
-* A More Detailed Example::     
-* Creating a Wrapper Module::   
-* Defining New Wrapped Types::  
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top The G-Wrap Reference Manual
 
-API Reference
+@insertcopying
+@sp 1
+@end ifnottex
 
-* Basic Concepts::              
-* G-Wrap's High-level API::     
-* G-Wrap's Code Generation API::  
+@menu
 
-Basic Concepts
+* Preface::
+* Introduction::
 
-* Wrapsets::                    
-* Wrapped Types::               
-* Typespecs::                   
-* Wrapped Functions::           
+* A More Detailed Example::
+* API Reference::
 
-G-Wrap's High-level Interface
+Appendices
 
-* Wrapping a C Function::       
-* Wrapping a C Constant::       
-* Wrapping an Enumerate Type::  
-* Wrapping a C Pointer Type::   
-* C Types Provided in the Standard Wrapset::  
-* Wrapping Another Simple C Type::  
+* GNU Free Documentation License::  The license of this manual.
 
-G-Wrap's Code Generation Interface
+Indices
 
-* Overview of the Code Generation Methods::  
-* The Top-Level Methods::       
-* Wrapping and Unwrapping Values::  
+* Concept Index::
+* Procedure and Method Index::
+* Type and Class Index::
 
-@end detailmenu
 @end menu
 
-@c Chapter ==================================================================
-@node Copying, Introduction, Top, Top
-@chapter Copying
-
-@center Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995
-@center Free Software Foundation, Inc.
-@center 675 Mass Ave, Cambridge, MA 02139, USA
-
-@noindent
-Permission to use, copy, modify, distribute, and sell this software and
-its documentation for any purpose is hereby granted without fee,
-provided that the above copyright notice appear in all copies and that
-both that copyright notice and this permission notice appear in
-supporting documentation.
-
-@center NO WARRANTY
+@contents
 
-@noindent
-BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
-THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
-EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE
-ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
-YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
-NECESSARY SERVICING, REPAIR OR CORRECTION.
+@include preface.texi
 
-@noindent
-IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
-DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
-DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
-(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
-INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
-THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
-OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-
-@c Chapter ==================================================================
-@node Introduction, Usage, Copying, Top
+@node Introduction
 @chapter Introduction
 
-@menu
-* Overview::                    
-* Why Create a Wrapper Generator?::  
-@end menu
-
-@node Overview, Why Create a Wrapper Generator?, Introduction, Introduction
-@section Overview
+G-Wrap is a tool (and guile library) for generating function wrappers
+for inter-language calls. It currently only supports generating Guile
+wrappers for C functions. Other languages may be supported in the
+future, possibly on both sides.
 
 Given a definition of the types and prototypes for a given C interface,
 G-Wrap will automatically generate the C code that provides access to
@@ -180,6 +125,61 @@ programmatic one.  You tell G-Wrap about your functions and types, and
 ask it to generate wrappers for you by calling the functions exported
 from the @code{(g-wrap)} module.
 
+G-Wrap heavily uses
+@uref{http://www.gnu.org/software/guile/manual/html_node/GOOPS.html#GOOPS,
+GOOPS} Guile's object orientation framework.  This is what makes
+G-Wrap highly customizable: each code generation methods may be
+overloaded or redefined in order to meet the user's particular needs.
+
+@menu
+* Why Create a Wrapper Generator?::
+* Obtaining and Installing G-Wrap::
+* A Simple Example::
+@end menu
+
+@node Why Create a Wrapper Generator?
+@section Why Create a Wrapper Generator?
+
+When accessing a given foreign API from a variety of target languages,
+the description of the foreign API is a common bit of information that
+will be needed by the infrastructure supporting each of the target
+languages.  Further, since the internal mechanisms by which a given
+target language can access a foreign API are often in flux, it makes
+sense to consider automatically generating the "glue code" that binds
+the library API and the target language together.  This means that
+whenever the foreign function access mechanisms in a target language
+change, only G-Wrap (or some similar tool) will need to be updated.
+Then all of the relevant glue code can be trivially re-generated.  This
+is the job that G-Wrap was designed to handle.
+
+In truth, one of the primary goals of G-Wrap is also to acumulate as
+many language independent definitions of various APIs as possible, so
+that interfaces for other languages may be generated automatically,
+whether by G-Wrap, or some other program.
+
+The original motivation for G-Wrap came from Aubrey Jaffer's suggestion
+to Christopher Lee that using Scheme to parse a language neutral API
+specification and generate glue code would be a good way to address this
+problem for Scheme interpreters.  G-Wrap may well evolve beyond that to
+support other languages, but for now, it only handles access to C APIs
+from Guile.
+
+In fact, the original implementation of G-Wrap was much more declarative
+than programmatic.  The API specification files were not executable
+Scheme code, but rather declarative Scheme forms.  In the long run, this
+might be preferable, if G-Wrap decides to move in the direction of
+language independence, or an alternate possibility is to design a
+language neutral API spec file (as guile-gnome is trying to do) and then
+just have a translator from that to native G-Wrap calls.
+
+
+@include install.texi
+
+
+@node A Simple Example
+@section A Simple Example
+
+
 As a simple example, if you wanted to wrap a C API that contained only
 one function with a prototype like this
 
@@ -211,7 +211,7 @@ a complete G-Wrap specification would look like this:
   (next-method)
 
   ;; Populate the wrapset.
-  (wrap-function! ws 
+  (wrap-function! ws
                   #:name 'frob
                   #:returns 'int
                   #:arguments '((int x) (double y))
@@ -329,62 +329,12 @@ modules to be able to safely exchange data among their wrapped
 functions when they share common wrapped types.
 
 As mentioned, G-Wrap itself is implemented as purely Scheme-code Guile
-modules.  This means that you you can wrap functions for multiple
+modules.  This means that you can wrap functions for multiple
 modules on the fly from any invocation of Guile.
 
-@node Why Create a Wrapper Generator?,  , Overview, Introduction
-@section Why Create a Wrapper Generator?
 
-When accessing a given foreign API from a variety of target languages,
-the description of the foreign API is a common bit of information that
-will be needed by the infrastructure supporting each of the target
-languages.  Further, since the internal mechanisms by which a given
-target language can access a foreign API are often in flux, it makes
-sense to consider automatically generating the "glue code" that binds
-the library API and the target language together.  This means that
-whenever the foreign function access mechanisms in a target language
-change, only G-Wrap (or some similar tool) will need to be updated.
-Then all of the relevant glue code can be trivially re-generated.  This
-is the job that G-Wrap was designed to handle.
-
-In truth, one of the primary goals of G-Wrap is also to acumulate as
-many language independent definitions of various APIs as possible, so
-that interfaces for other languages may be generated automatically,
-whether by G-Wrap, or some other program.
-
-The original motivation for G-Wrap came from Aubrey Jaffer's suggestion
-to Christopher Lee that using Scheme to parse a language neutral API
-specification and generate glue code would be a good way to address this
-problem for Scheme interpreters.  G-Wrap may well evolve beyond that to
-support other languages, but for now, it only handles access to C APIs
-from Guile.
-
-In fact, the original implementation of G-Wrap was much more declarative
-than programmatic.  The API specification files were not executable
-Scheme code, but rather declarative Scheme forms.  In the long run, this
-might be preferable, if G-Wrap decides to move in the direction of
-language independence, or an alternate possibility is to design a
-language neutral API spec file (as gnome-guile is trying to do) and then
-just have a translator from that to native G-Wrap calls.
-
-G-Wrap can be found at @url{http://www.nongnu.org/g-wrap/}.
-
-@c Chapter ==================================================================
-@node Usage, API Reference, Introduction, Top
-@chapter Usage
-
-This section is a guided tour through G-Wrap programmatic interface
-that will get you started quickly by looking at practical examples.
-For a more detailed view of the API, please see @xref{API Reference}.
-
-@menu
-* A More Detailed Example::     
-* Creating a Wrapper Module::   
-* Defining New Wrapped Types::  
-@end menu
-
-@node A More Detailed Example, Creating a Wrapper Module, Usage, Usage
-@section A More Detailed Example
+@node A More Detailed Example
+@chapter A More Detailed Example
 
 In this chapter we'll walk through the process of wrapping an
 increasingly complex C API.  In the process, we'll try to hit all the
@@ -414,7 +364,16 @@ functions and types.  Conventionally, if you're creating a wrapper
 module named "foo", the wrapset specification file would be named
 foo-spec.scm, or placed in separate @file{ws/} subdirectory.
 
-@node Creating a Wrapper Module, Defining New Wrapped Types, A More Detailed Example, Usage
+
+@menu
+* Creating a Wrapper Module::
+* Defining New Wrapped Types::
+* The @code{aggregated} Type Qualifier::
+* Reporting Bugs::
+@end menu
+
+
+@node Creating a Wrapper Module
 @section Creating a Wrapset
 
 Inside the wrapset specification file, the first thing you have to do
@@ -458,11 +417,11 @@ want to say something like this:
   (define-method (initialize (ws <miscutils-wrapset>) initargs)
     (next-method ws (append '(#:module (miscutils)) initargs))
 
-    (wrap-function! 
+    (wrap-function!
       ws
       #:name 'join_strings
       #:returns 'mchars
-      #:c-name "join_strings" 
+      #:c-name "join_strings"
       #:arguments '((mchars a) (mchars b))
       #:description "Return a string consisting of a followed by b.")
 
@@ -470,7 +429,7 @@ want to say something like this:
      ws
      #:name 'seconds-since-dow
      #:returns 'double
-     #:c-name "seconds_since_dow" 
+     #:c-name "seconds_since_dow"
      #:arguments '((uint day-of-week))
      #:description "Given day-of-week (ranging 1-7), return elapsed time since then."))
 @end example
@@ -499,11 +458,11 @@ string that will also be owned by the caller.  Given that, the correct
 way to wrap this function is:
 
 @example
-    (wrap-function! 
+    (wrap-function!
       ws
       #:name 'join-strings
       #:returns '(mchars caller-owned)
-      #:c-name "join_strings" 
+      #:c-name "join_strings"
       #:arguments '(((mchars caller-owned) a) ((mchars caller-owned) b))
       #:description "Return a string consisting of a followed by b.")
 @end example
@@ -522,7 +481,8 @@ these C functions normally.  You could use it like this:
   guile>
 @end example
 
-@node Defining New Wrapped Types,  , Creating a Wrapper Module, Usage
+
+@node Defining New Wrapped Types
 @section Defining New Wrapped Types
 
 Though G-Wrap already provides a number of wrapped types in the
@@ -532,13 +492,13 @@ define your own wrapped types.
 As an example, let's presume someone has added a fine-grained, wide
 ranging, time type to miscutils along with a function that uses that
 type like this:
- 
+
 FIXME: Add an overview of how G-Wrap thinks about types -- i.e. using a
 template-like process with ccodegens inserting content in important
 places.
 
 @example
- 
+
   typedef struct @{
     long long seconds;
     long int nanoseconds;
@@ -611,7 +571,7 @@ the Scheme side.
     (list
       "if (SCM_FALSEP(msu_scm_timespec64_p(" (scm-var value) ")))"
       `(gw:error ,error-var type ,(wrapped-var value))
-      "else\n"  
+      "else\n"
       "  " (var value) " = msu_timespec64_to_c(" (scm-var value) ");\n"))
 @end lisp
 
@@ -657,8 +617,11 @@ nothing overly fancy, you can get away with just @code{wrap-value-cg},
 @code{unwrap-value-cg}. For C values that need deconstruction, there
 is also @code{destruct-value-cg}.
 
-@c Chapter ==================================================================
-@node API Reference, Concept Index, Usage, Top
+@include aggregate.texi
+@include report-bugs.texi
+
+
+@node API Reference
 @chapter API Reference
 
 This section is trying to provide a reference for the most important
@@ -677,9 +640,9 @@ In any case, reading the section @xref{Basic Concepts}, is highly
 recommended since it describes concepts used throughout G-Wrap.
 
 @menu
-* Basic Concepts::              
-* G-Wrap's High-level API::     
-* G-Wrap's Code Generation API::  
+* Basic Concepts::
+* G-Wrap's High-level API::
+* G-Wrap's Code Generation API::
 @end menu
 
 @node Basic Concepts, G-Wrap's High-level API, API Reference, API Reference
@@ -692,20 +655,21 @@ The Goops Reference Manual}) usually exported by the @code{(g-wrap)}
 module.
 
 @menu
-* Wrapsets::                    
-* Wrapped Types::               
-* Typespecs::                   
-* Wrapped Functions::           
+* Wrapsets::
+* Wrapped Types::
+* Typespecs::
+* Wrapped Functions::
 @end menu
 
-@node Wrapsets, Wrapped Types, Basic Concepts, Basic Concepts
+
+@node Wrapsets
 @subsection Wrapsets
 
 @cindex wrapset
 @tindex <gw-wrapset>
 A wrapset is roughly an object that holds a representation of all the
 C types, constants, and functions what one is willing to ``wrap''.
-Wrapset specifications as seen in @xref{Overview}, are in fact a piece
+Wrapset specifications as seen in @xref{A Simple Example}, are in fact a piece
 of Scheme code that creates a wrapset object, adds a number of C
 functions, types, etc. to be wrapped and then generates code for this
 wrapset.  The code generation phase will be described in more details
@@ -831,7 +795,8 @@ call @var{proc} (a procedure or generic function).  The result is
 unspecified.
 @end deffn
 
-@node Wrapped Types, Typespecs, Wrapsets, Basic Concepts
+
+@node Wrapped Types
 @subsection Wrapped Types
 
 @tindex <gw-type>
@@ -928,15 +893,14 @@ unwraps, or destroys instances of the C type wrapped by @var{type}
 @end deffn
 
 
-
-@node Typespecs, Wrapped Functions, Wrapped Types, Basic Concepts
+@node Typespecs
 @subsection Typespecs
 
 @tindex <gw-typespec>
 FIXME: Write it; see also @xref{Wrapping a C Function}.
 
 
-@node Wrapped Functions,  , Typespecs, Basic Concepts
+@node Wrapped Functions
 @subsection Wrapped Functions
 
 @tindex <gw-function>
@@ -948,7 +912,8 @@ FIXME: Write it; see also @xref{Wrapping a C Function}.
 FIXME: Describe
 @end deffn
 
-@node G-Wrap's High-level API, G-Wrap's Code Generation API, Basic Concepts, API Reference
+
+@node G-Wrap's High-level API
 @section G-Wrap's High-level Interface
 
 G-Wrap's high-level API lives in the @code{(g-wrap)} module, and
@@ -967,18 +932,19 @@ however, may be achieved using the lower-level code generation API
 (@pxref{G-Wrap's Code Generation API}).
 
 @menu
-* Wrapping a C Function::       
-* Wrapping a C Constant::       
-* Wrapping an Enumerate Type::  
-* Wrapping a C Pointer Type::   
-* C Types Provided in the Standard Wrapset::  
-* Wrapping Another Simple C Type::  
+* Wrapping a C Function::
+* Wrapping a C Constant::
+* Wrapping an Enumerate Type::
+* Wrapping a C Pointer Type::
+* C Types Provided in the Standard Wrapset::
+* Wrapping Another Simple C Type::
 @end menu
 
-@node Wrapping a C Function, Wrapping a C Constant, G-Wrap's High-level API, G-Wrap's High-level API
+
+@node Wrapping a C Function
 @subsection Wrapping a C Function
 
-As seen in @xref{Overview}, wrapping a C function using G-Wrap's
+As seen in @xref{A Simple Example}, wrapping a C function using G-Wrap's
 high-level functions is relatively simple.  Essentially, it boils down
 to a call to the @code{wrap-function!} GOOPS method.
 
@@ -988,7 +954,7 @@ be wrapped by @var{wrapset}.  The arguments in @var{args} must contain
 the following named parameters (@pxref{Optional Arguments,
 @code{(ice-9 optargs)},, guile, The GNU Guile Reference Manual}):
 
-@c FIXME: This is (mostly) copied from the `Overview' section.
+@c FIXME: This is (mostly) copied from the `A Simple Example' section.
 @table @code
 @item #:name
 the symbol which should be bound to the wrapped function in Scheme at
@@ -1070,93 +1036,7 @@ Examples of valid usage patterns of @code{wrap-function!} are
 available in @xref{Creating a Wrapper Module}.
 
 
-@unnumbered The @code{aggregated} Type Qualifier
-
-@cindex memory management
-@cindex aggregated object
-@cindex constructor
-The @code{aggregated} type qualifier is mostly useful when wrapping C
-functions (constructors) that return a new object which aggregates
-objects passed as its input parameters.  In order to illustrate the
-need for this typespec, let's imagine the following C API:
-
-@smallexample
-/* Return a new stuff.  */
-stuff_t *make_stuff (void);
-
-/* Return a stuff container that contains a pointer to CONTAINED.
-   Note that the container returned is _not_ responsible for
-   deallocating the resources attached to CONTAINED.  */
-stuff_container_t *make_stuff_container (stuff_t *contained);
-@end smallexample
-
-And now, imagine the following Scheme code that uses bindings of the
-above functions:
-
-@smalllisp
-(define c (make-stuff-container (make-stuff)))
-@end smalllisp
-
-Suppose the two C types are wrapped as WCTs (@pxref{Wrapping a C
-Pointer Type}).  The call to @code{make-stuff} will create a new
-Scheme object (a WCP, or a ``SMOB'' in Guile terms, @pxref{Defining
-New Types (Smobs), SMOBs,, guile, The GNU Guile Reference Manual}) for
-the underlying C object.  However, as soon as
-@code{make-stuff-container} has returned, the Scheme code no longer
-holds any SMOB representing the value that was returned by
-@code{make-stuff}.  Consequently, the SMOB returned by
-@code{make-stuff} may soon be garbage-collected by Guile, and its
-underlying C object (originally returned by @code{make_stuff ()}) may
-soon get freed as well.
-
-But, here is the problem: the C @code{stuff_container_t} object still
-contains a pointer to that @code{stuff_t} object that has just been
-deleted!  The goal of the @code{aggregated} typespec is to solve
-situations like this one.  In the example above, the wrapped function
-and the container type should be specified as follows:
-
-@lisp
-(wrap-as-wct! ws
-              #:name '<stuff>
-              #:c-type-name "stuff_t *"
-              #:c-const-type-name "const stuff_t *"
-              #:allowed-options '(aggregated))
-
-...
-
-(wrap-function! ws
-                #:name 'make-stuff-container
-                #:c-name "make_stuff_container"
-                #:returns '<stuff-container>
-                #:arguments '(((<stuff> aggregated) stuff)))
-@end lisp
-
-Literally, this means: ``the argument @var{stuff} of
-@code{make-stuff-container} is @emph{aggregated} by the object
-returned by @code{make-stuff-container}; therefore, it may not be GC'd
-unless the object returned by @code{make-stuff-container} is GC'd
-too.''
-
-@cindex finalization order
-Additionally, G-Wrap, in this case, enforces the @emph{finalization
-order} of WCPs: even if both the referrer (the
-@code{<stuff-container>} object) and its dependency (the @var{stuff}
-argument) become unreachable during the same GC phase, G-Wrap makes
-sure that their @code{wcp-free-function}s (@pxref{Wrapping a C Pointer
-Type}) are called in the right order, i.e., referrer first, dependency
-second.
-
-@cindex reference counting
-Note that some libraries, such as GTK+, solve this problem by relying
-on reference counting: aggregating objects must increment the
-reference counter of the objects they refer to.  The @code{aggregated}
-type qualifier facility can be seen as a solution for those C
-libraries that do @emph{not} use reference counting but have memory
-ownership semantics similar to the ones described above.  An example
-of such a library is Berkeley DB.
-
-
-@node Wrapping a C Constant, Wrapping an Enumerate Type, Wrapping a C Function, G-Wrap's High-level API
+@node Wrapping a C Constant
 @subsection Wrapping a C Constant
 
 @deffn method wrap-constant! (wrapset <gw-wrapset>) . args
@@ -1180,7 +1060,8 @@ a string describing this constant.
 
 @end deffn
 
-@node Wrapping an Enumerate Type, Wrapping a C Pointer Type, Wrapping a C Constant, G-Wrap's High-level API
+
+@node Wrapping an Enumerate Type
 @subsection Wrapping an Enumerate Type
 
 When wrapping a whole C enumerate type, G-Wrap proposes an interface
@@ -1223,7 +1104,7 @@ This can be used as follows:
 @end deffn
 
 
-@node Wrapping a C Pointer Type, C Types Provided in the Standard Wrapset, Wrapping an Enumerate Type, G-Wrap's High-level API
+@node Wrapping a C Pointer Type
 @subsection Wrapping a C Pointer Type
 
 @cindex wrapped C type
@@ -1315,10 +1196,10 @@ field does get marked.
 A string describing this wrapped C type.
 @end table
 
-
 @end deffn
 
-@node C Types Provided in the Standard Wrapset, Wrapping Another Simple C Type, Wrapping a C Pointer Type, G-Wrap's High-level API
+
+@node C Types Provided in the Standard Wrapset
 @subsection C Types Provided in the Standard Wrapset
 
 @cindex standard wrapset
@@ -1399,7 +1280,7 @@ qualifiers to the string argument of the wrapped function, such as
 @code{caller-owned} (@pxref{Wrapping a C Function}).
 
 
-@node Wrapping Another Simple C Type,  , C Types Provided in the Standard Wrapset, G-Wrap's High-level API
+@node Wrapping Another Simple C Type
 @subsection Wrapping Another Simple C Type
 
 If you want to wrap a simple C type which is does not fit in any of
@@ -1474,7 +1355,7 @@ to do, then you may have a look at the details of G-Wrap's code
 generation interface, @xref{G-Wrap's Code Generation API}.
 
 
-@node G-Wrap's Code Generation API,  , G-Wrap's High-level API, API Reference
+@node G-Wrap's Code Generation API
 @section G-Wrap's Code Generation Interface
 
 When creating Scheme bindings for a C programming interface with
@@ -1484,23 +1365,25 @@ been added to it, G-Wrap is ready to proceed with the generation of
 C code implementing these wrappings.
 
 In the following sections, we will detail the @dfn{protocol} that is
-used to perform code generation.  G-Wrap heavily uses GOOPS, Guile's
-object orientation framework, to this end (@pxref{Top, Guile's
-Object-Oriented Programming System,, goops, The GOOPS Reference
-Manual}).  This is what makes G-Wrap highly customizable: each of
-these code generation methods may be overloaded or redefined in order
-to meet the user's particular needs.
+used to perform code generation.
+
+As mentionned in the introduction, G-Wrap heavily uses @pxref{GOOPS,,,
+guile, The GNU Guile Reference Manual}, Guile's object orientation
+framework.  This is what makes G-Wrap highly customizable: each code
+generation methods may be overloaded or redefined in order to meet the
+user's particular needs.
 
 Most of the classes and methods involved in generation of C code are
 defined in the @code{(g-wrap c-codegen)}.
 
 @menu
-* Overview of the Code Generation Methods::  
-* The Top-Level Methods::       
-* Wrapping and Unwrapping Values::  
+* Overview of the Code Generation Methods::
+* The Top-Level Methods::
+* Wrapping and Unwrapping Values::
 @end menu
 
-@node Overview of the Code Generation Methods, The Top-Level Methods, G-Wrap's Code Generation API, G-Wrap's Code Generation API
+
+@node Overview of the Code Generation Methods
 @subsection Overview of the Code Generation Methods
 
 @cindex code generation methods
@@ -1553,7 +1436,7 @@ described above.
 @end deffn
 
 
-@node The Top-Level Methods, Wrapping and Unwrapping Values, Overview of the Code Generation Methods, G-Wrap's Code Generation API
+@node The Top-Level Methods
 @subsection The Top-Level Methods
 
 As we have just seen, wrapset objects (i.e. instances of a sub-class
@@ -1615,7 +1498,8 @@ of it).
 
 FIXME: To be continued.
 
-@node Wrapping and Unwrapping Values,  , The Top-Level Methods, G-Wrap's Code Generation API
+
+@node Wrapping and Unwrapping Values
 @subsection Wrapping and Unwrapping Values
 
 For each specific wrapped type, a specific sequence of C code must be
@@ -1704,24 +1588,35 @@ Since G-Wrap allows to construct function calls at run-time via libffi
 run-time call constructor.
 @end deffn
 
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
 
-@c Chapter ==================================================================
-@node Concept Index, Type and Class Index, API Reference, Top
+@node Concept Index
 @unnumbered Concept Index
 
+This index contains concepts, keywords and non-Schemey names for
+several features, to make it easier to locate the desired sections.
+
 @printindex cp
 
-@node Type and Class Index, Procedure and Method Index, Concept Index, Top
-@unnumbered Type and Class Index
 
-@printindex tp
-
-@node Procedure and Method Index,  , Type and Class Index, Top
+@node Procedure and Method Index
 @unnumbered Procedure and Method Index
 
+This is an alphabetical list of all the procedures and macros in
+G-Wrap.
+
 @printindex fn
 
-@contents
+
+@node Type and Class Index
+@unnumbered Type and Class Index
+
+@printindex tp
+
+
 @bye
 
 @c Local Variables:
diff --git a/doc/install.texi b/doc/install.texi
new file mode 100644
index 0000000..d4cca5a
--- /dev/null
+++ b/doc/install.texi
@@ -0,0 +1,41 @@
+@c -*-texinfo-*-
+@c This is part of the G-Wrap Reference Manual.
+@c Copyright (C)  2014 David Pirotte
+@c See the file g-wrap.texi for copying conditions.
+
+@node Obtaining and Installing G-Wrap
+@section Obtaining and Installing G-Wrap
+
+G-Wrap can be obtained from the main GNU archive site
+@url{http://download.savannah.gnu.org/releases/g-wrap/} or any of its
+mirrors.  The file will be named g-wrap-@var{version}.tar.gz.  The
+current version is @value{VERSION}, so the file you should grab is:
+
+@url{http://download.savannah.gnu.org/releases/g-wrap/g-wrap-@value{VERSION}.tar.gz}
+
+To unbundle G-Wrap use the instruction
+
+@example
+zcat g-wrap-@value{VERSION}.tar.gz | tar xvf -
+@end example
+
+@noindent
+which will create a directory called @file{g-wrap-@value{VERSION}} with
+all the sources.  You can look at the file @file{INSTALL} for detailed
+instructions on how to build and install G-Wrap, but you should be able
+to just do
+
+@example
+cd g-wrap-@value{VERSION}
+./configure --prefix=...
+make
+make install
+@end example
+
+This will install the G-Wrap files in @file{<prefix>/share/guile/site/g-wrap}.
+
+
+@c Local Variables:
+@c TeX-master: "g-wrap.texi"
+@c ispell-local-dictionary: "american"
+@c End:
diff --git a/doc/preface.texi b/doc/preface.texi
new file mode 100644
index 0000000..2e90c8c
--- /dev/null
+++ b/doc/preface.texi
@@ -0,0 +1,63 @@
+@c -*-texinfo-*-
+@c This is part of the G-Wrap Reference Manual.
+@c Copyright (C)  2014 David Pirotte
+@c See the file g-wrap.texi for copying conditions.
+
+@node Preface
+@unnumbered Preface
+
+This manual describes how to use G-Wrap.  It relates particularly to
+G-Wrap version @value{VERSION}.
+
+@menu
+* Contributors::                
+* G-Wrap License::               
+@end menu
+
+@node Contributors
+@unnumberedsec Contributors to this Manual
+
+The contributors to the G-Wrap manual are:
+
+@itemize @bullet
+@item Christopher Lee <chrislee@@ri.cmu.edu>
+@item Rob Browning <rlb@@defaultvalue.org>
+@item Andreas Rottmann <rotty@@debian.org>
+@item Ludovic Courtès <ludovic.courtes@@laas.fr>
+@item David Pirotte <david@@altosw.be>
+@end itemize
+
+If you find any problems in this manual, please report a bug.  See
+@xref{Reporting Bugs}, for more information on how to report a bug.
+
+@node G-Wrap License
+@unnumberedsec The G-Wrap License
+@cindex copying
+@cindex GPL
+@cindex LGPL
+@cindex license
+
+G-Wrap is Free Software.  G-Wrap is copyrighted, not public domain, and
+there are restrictions on its distribution or redistribution, but
+these restrictions are designed to permit everything a cooperating
+person would want to do.
+
+@itemize @bullet
+@item
+G-Wrap and supporting files are published under the terms of the GNU
+Lesser General Public License version 2 or later.  See the file
+@file{COPYING.LIB}.
+
+@item
+The manual you're now reading is published under the terms of the GNU
+Free Documentation License (@pxref{GNU Free Documentation License}).
+@end itemize
+
+You must be aware there is no warranty whatsoever for G-Wrap.  This is
+described in full in the licenses.
+
+
+@c Local Variables:
+@c TeX-master: "g-wrap.texi"
+@c ispell-local-dictionary: "american"
+@c End:
diff --git a/doc/report-bugs.texi b/doc/report-bugs.texi
new file mode 100644
index 0000000..d521e70
--- /dev/null
+++ b/doc/report-bugs.texi
@@ -0,0 +1,61 @@
+@c -*-texinfo-*-
+@c This is part of the G-Wrap Reference Manual.
+@c Copyright (C)  2014 David Pirotte
+@c See the file g-wrap.texi for copying conditions.
+
+
+@node Reporting Bugs
+@section Reporting Bugs
+
+Any problems with the installation should be reported to
+@email{bug-guile@@gnu.org}.
+
+If you find a bug in G-Wrap, please report it to the Guile developers,
+so they can fix it.  When you write a bug report, please make sure to
+include as much of the information described below in the report.  If
+you can't figure out some of the items, it is not a problem, but the
+more information we get, the more likely we can diagnose and fix the
+bug.
+
+@itemize @bullet
+
+@item
+The version number of G-Wrap.  This manual documents G-Wrap version
+@value{VERSION}.
+
+@item
+The version number of Guile. You can get this information from invoking
+@samp{guile --version} at your shell, or calling @code{(version)} from
+within Guile.
+
+@item
+A complete description of how to reproduce the bug.
+
+If you have a Scheme program that produces the bug, please include it
+in the bug report. If your program is too big to include. please try
+to reduce your code to a minimal test case.
+
+@item
+A description of the incorrect behavior.  For example, "The Guile
+process gets a fatal signal," or, "The resulting output is as follows,
+which I think is wrong."
+
+If the manifestation of the bug is a Guile error message, it is
+important to report the precise text of the error message, and a
+backtrace showing how the Scheme program arrived at the error. This
+can be done using the @code{,backtrace} command in Guile's debugger.
+@end itemize
+
+If your bug causes Guile to crash, additional information from a
+low-level debugger such as GDB might be helpful. If you have built
+Guile yourself, you can run Guile under GDB via the
+@code{meta/gdb-uninstalled-guile} script. Instead of invoking Guile as
+usual, invoke the wrapper script, type @code{run} to start the
+process, then @code{backtrace} when the crash comes. Include that
+backtrace in your report.
+
+
+@c Local Variables:
+@c TeX-master: "g-wrap.texi"
+@c ispell-local-dictionary: "american"
+@c End:
diff --git a/doc/version.texi b/doc/version.texi
new file mode 100644
index 0000000..fe62118
--- /dev/null
+++ b/doc/version.texi
@@ -0,0 +1,4 @@
+@set UPDATED 11 July 2012
+@set UPDATED-MONTH July 2012
+@set EDITION 1.9.14
+@set VERSION 1.9.14
-- 
2.0.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 190 bytes --]

^ permalink raw reply related	[flat|nested] 2+ messages in thread