summaryrefslogtreecommitdiff
path: root/doc/ref/extend.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/extend.texi')
-rw-r--r--doc/ref/extend.texi44
1 files changed, 44 insertions, 0 deletions
diff --git a/doc/ref/extend.texi b/doc/ref/extend.texi
new file mode 100644
index 000000000..5c72bef33
--- /dev/null
+++ b/doc/ref/extend.texi
@@ -0,0 +1,44 @@
+@page
+@node Libguile Intro
+@chapter Using Guile as an Extension Language
+
+The chapters in this part of the manual explain how to use Guile as a
+powerful application extension language.
+
+An important change for the 1.6.x series of Guile releases is that the
+GH interface is now deprecated. For the reasoning behind this decision,
+see @xref{GH deprecation}. The GH interface will continue to be
+supported for the 1.6.x and 1.8.x release series, but will be dropped
+thereafter, so developers are encouraged to switch progressively to the
+scm interface. The last chapter in this part of the manual (@pxref{GH})
+documents both how to use GH and how to switch from GH to scm.
+
+The Guile developers believe that clarification of the GH vs. scm
+debate, and the consequent deprecation of the GH interface, are in the
+long term interests of the project. However it does create an
+unfortunate situation for developers who want to start a project using
+Guile and so read the manual to find out how to proceed. They will
+discover that the GH interface, although quite well documented, is
+deprecated, but that there is almost no adequate documentation for its
+theoretical replacement, the scm interface. Moreover, the scm interface
+still has the odd few rough edges which need smoothing down.
+
+Therefore, although deprecated, it is quite OK to continue to use the GH
+interface if you feel uncomfortable with the `scm_' interface as it
+stands today. By the time that support for GH is dropped, we plan to
+have thoroughly documented the `scm_' interface, and to have enhanced it
+such that conversion from GH to the `scm_' interface will be very
+straightforward, and probably mostly automated.
+
+As far as documentation of the scm interface is concerned, the current
+position is that it is a bit confused, but that the situation should
+improve rapidly once the 1.6.0 release is out. The plan is to refocus
+the bulk of Part II, currently ``Guile Scheme'', as the ``Guile API
+Reference'' so that it covers both Scheme and C interfaces. (This makes
+sense because almost all of Guile's primitive procedures on the Scheme
+level --- e.g. @code{memq} --- are also available as C level primitives
+in the scm interface --- e.g. @code{scm_memq}.) There will then remain
+a certain amount of Scheme-specific (such as the ``Basic Ideas''
+chapter) and C-specific documentation (such as SMOB usage and
+interaction with the garbage collector) to collect into corresponding
+chapters.