From 32759790e67e8f538bb2b15cd916663355d785fa Mon Sep 17 00:00:00 2001 From: David PIROTTE Date: Mon, 22 Sep 2014 02:01:08 -0300 Subject: [PATCH 2/2] g-wrap reference manual introduction review and xref fixes * doc/g-wrap.texi: last section of the introduction, 'A Simple Example' needed a bit of a structure to help the reader, I think. So I added a couple of subheadings and made small changes preeceding and following these. xref fixes related to the guile reference manual, (goops and the GC mainly). * doc/.gitignore: added with a g-wrap entry, since we don't want to track html pages. --- doc/.gitignore | 1 + doc/g-wrap.texi | 57 +++++++++++++++++++++++++++++++-------------------------- 2 files changed, 32 insertions(+), 26 deletions(-) create mode 100644 doc/.gitignore diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..3ede455 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +g-wrap diff --git a/doc/g-wrap.texi b/doc/g-wrap.texi index abc95f0..3181cc5 100644 --- a/doc/g-wrap.texi +++ b/doc/g-wrap.texi @@ -70,7 +70,7 @@ for use with G-Wrap @value{VERSION} @set example-dir guile/examples @ifnottex -@node Top, Introduction, (dir), (dir) +@node Top, Preface, (dir), (dir) @top The G-Wrap Reference Manual @insertcopying @@ -125,11 +125,11 @@ 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. +G-Wrap heavily uses GOOPS, Guile's object oriented extension +(@pxref{GOOPS,,, guile, The GNU Guile Reference Manual}) . 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?:: @@ -179,9 +179,10 @@ just have a translator from that to native G-Wrap calls. @node A Simple Example @section A Simple Example +@subheading Defining and exporting your wrapset class As a simple example, if you wanted to wrap a C API that contained only -one function with a prototype like this +one function with a prototype like this: @example int frob(int x, double y); @@ -193,16 +194,13 @@ a complete G-Wrap specification would look like this: @lisp (define-module (my-wrapset) #:use-module (oop goops) - - #:use-module (g-wrap) ;; the core of G-Wrap - #:use-module (g-wrap guile) ;; defines `' - - #:use-module (g-wrap guile ws standard) ;; the `standard' wrapset + #:use-module (g-wrap) ;; the core of G-Wrap + #:use-module (g-wrap guile) ;; defines `' + #:use-module (g-wrap guile ws standard) ;; the `standard' wrapset #:export ()) -;; Define a wrapset for Guile, and specify the wrapsets -;; it depends on. +;; Define a wrapset for Guile, and specify the wrapsets it depends on. (define-class () #:id 'my-wrapset #:dependencies '(standard)) @@ -234,6 +232,8 @@ globally unique identifier, and declares a dependency on the @code{initialize} method, the @code{frob} function is wrapped, providing all relevant data such as return and argument types. +@subheading Further customizations for Guile + To refine the above wrapset for Guile, you derive from it and add the necessary information: @@ -261,7 +261,8 @@ We derive our Guile-specific wrapset from the generic wrapset the wrapset should eventually reside in the Guile module @code{my-module}. -@noindent +@subheading Let's generate the C code, compile and use it + Once G-Wrap has seen this specification, the code for the wrappers can be generated with this code: @@ -272,7 +273,7 @@ be generated with this code: (generate-wrapset 'guile 'my-wrapset "my-wrapset") @end lisp -@noindent + This will produce the C file @file{my-wrapset.c}, that can be compiled into a shared library which will, when loaded by Guile, define a Scheme function named @code{frob} which you can call as expected: @@ -281,6 +282,8 @@ Scheme function named @code{frob} which you can call as expected: (frob 4 2.3) @end lisp +@subheading G-wrap is very flexible! + When it comes to defining how C types should be handled, G-Wrap is very flexible. G-Wrap provides a fairly generic underlying infrastructure which can then be customized for particular purposes by @@ -295,8 +298,11 @@ At the lowest level, there is a "wrapping protocol" for types, which you can plug into to describe how a type is converted from and to the target language as well as other aspects of the type. G-Wrap comes with a few of these more types pre-defined. This set should cover -most of the common cases, but you can extend this set if needed. The -wrapper types currently available by default include: +most of the common cases, but you can extend it if needed. + +@subheading Predefined wrapper types + +The wrapper types currently available by default include: @table @samp @@ -645,14 +651,13 @@ recommended since it describes concepts used throughout G-Wrap. * G-Wrap's Code Generation API:: @end menu -@node Basic Concepts, G-Wrap's High-level API, API Reference, API Reference +@node Basic Concepts @section Basic Concepts G-Wrap's APIs are centered around a few basic concepts that one should know before using them. Basically, each concept has a corresponding -GOOPS class (@pxref{Introduction, an introduction to GOOPS,, goops, -The Goops Reference Manual}) usually exported by the @code{(g-wrap)} -module. +GOOPS class usually exported by the @code{(g-wrap)} module +(@pxref{GOOPS,,, guile, The GNU Guile Reference Manual}). @menu * Wrapsets:: @@ -717,8 +722,8 @@ know them, except @code{initialize}. @deffn method initialize (wrapset ) . args Initialize @var{wrapset}, an newly created instance of @var{}. This method is part of the GOOPS meta-object -protocol (@pxref{Instance Creation, GOOPS MOP specification,, goops, -The GOOPS Reference Manual}). +protocol (@pxref{Instance Creation Protocol,,, guile, +The GNU Guile Reference Manual}). @cindex module @cindex Guile module @@ -1167,7 +1172,7 @@ relevant only to wrapsets targeting Guile. @cindex mark and sweep @cindex memory management Guile's garbage-collector uses a @dfn{mark and sweep} algorithm -(@pxref{Garbage Collecting Smob, the description of Guile's GC +(@pxref{Conservative GC, the description of Guile's GC mechanism,, guile, The GNU Guile Reference Manual}). This parameter allows to direct the mark phase for the specific C type being wrapped, using the same protocol as the one used for SMOBs in Guile. @@ -1356,7 +1361,7 @@ generation interface, @xref{G-Wrap's Code Generation API}. @node G-Wrap's Code Generation API -@section G-Wrap's Code Generation Interface +@section G-Wrap's Code Generation API When creating Scheme bindings for a C programming interface with G-Wrap, one first needs to create a @dfn{wrapset} (@pxref{Wrapsets}). -- 2.1.0