guile-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Guile module system documentation committed


From: Neil Jerram
Subject: Re: Guile module system documentation committed
Date: 07 May 2001 23:33:55 +0100
User-agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7

>>>>> "Martin" == Martin Grabmueller <address@hidden> writes:

    Martin> I have committed it to CVS under the name

    Martin> guile-core/devel/modules/module-snippets.texi

    Martin> and would like some comments, [...]

This is wonderful!  I haven't given thought yet to any of the bigger
questions like (i) how it affects my understanding of the module
system as a whole and (ii) whether this should be incorporated into
one of the existing Guile manuals, but I do have a few typos and
followup questions for you ...  (presented below as a diff)

        Neil

Index: module-snippets.texi
===================================================================
RCS file: /cvs/guile/guile-core/devel/modules/module-snippets.texi,v
retrieving revision 1.1
diff -u -r1.1 module-snippets.texi
--- module-snippets.texi        2001/05/07 19:29:22     1.1
+++ module-snippets.texi        2001/05/07 22:25:36
@@ -109,7 +109,7 @@
 like and what operations are defined on it.
 
 Modules in Guile are instances of a data type @code{module}.  A module
-has the following fields.
+is a record with the following fields.
 
 @table @var
 @item obarray
@@ -171,7 +171,7 @@
 * Module Hierarchy::            The currently implemented hierarchy.
 * Modules and Interfaces::      How modules implement different scopes.
 * Modules and Environments::    Relation between modules and environments.
-* Modules Miscallenea::         Miscellaneous module procedures.
+* Modules Miscellanea::         Miscellaneous module procedures.
 @end menu
 
 
@@ -256,7 +256,7 @@
 underlying mechanisms, on which @code{use-modules} is built.
 
 Normally, you will not need to create new modules explicitly, adding
-definitions to it manually.  For more often, you will want to load some
+definitions to it manually.  Far more often, you will want to load some
 Scheme code from a file, and install its definitions into a module, only
 exporting the public bits.  This is what the procedure
 @code{resolve-module} is for.
@@ -308,10 +308,11 @@
 @var{m}.''
 
 @deffn procedure module-locally-bound? module sym
-Test if @var{sym} is bound in @var{module} directly, e.g. it does not
+Test if @var{sym} is bound in @var{module} directly, i.e. it does not
 suffice that @var{sym} is bound in one of the used modules of
 @var{module}.  @dfn{Bound} means that the symbol is interned and bound
-to some well-defined value.
+to some well-defined value.  NJFIXME - what does `well-defined' actually
+mean?
 @end deffn
 
 @deffn procedure module-bound? module sym
@@ -322,7 +323,7 @@
 @end deffn
 
 @deffn procedure module-symbol-locally-interned? module sym
-Test if @var{sym} is interned in @var{module} directly, e.g. it does not
+Test if @var{sym} is interned in @var{module} directly, i.e. it does not
 suffice that @var{sym} is bound in one of the used modules of
 @var{module}.  Unlike @code{module-locally-bound}, the symbol is not
 required to be bound to a well-defined value.
@@ -370,6 +371,7 @@
 
 @deffn procedure module-add! module symbol var
 Add the variable @var{var} to @var{module} under the name @var{symbol}.
+NJFIXME - what is the type of var here?
 @end deffn
 
 @deffn procedure module-remove! module symbol
@@ -390,6 +392,7 @@
 @deffn procedure module-for-each proc module
 Apply @var{proc} to every binding in @var{module}.  @var{proc} is called
 with two parameters, the name and variable for each binding.
+NJFIXME - local bindings? or this module plus its uses list recursively?
 @end deffn
 
 @deffn procedure module-map proc module
@@ -424,6 +427,9 @@
 @code{#t} if the binding should be defined, @code{#f} otherwise.
 @end table
 
+NJFIXME - presumably, if `define?' is #t, no recursion occurs, as the
+binding either exists in the first level module, or is created in the
+first level module - is this correct?
 
 @c ===================================================================
 
@@ -471,7 +477,7 @@
 For all evaluations, Guile maintains a so-called @dfn{current
 address@hidden current module does not exist until Guile has been
 completely booted, that means until @file{boot-9.scm} has been loaded.
-But this should be no issue unless you are doing weird things withe the
+But this should be no issue unless you are doing weird things with the
 module system, which might be a bad idea, but YMMV.}  This is used for
 all top-level definitions and variable lookups.  When the current module
 changes, new definitions will go to the new module.  The procedures in
@@ -516,6 +522,8 @@
 of its used modules.  If there is no such variable, then if the optional
 third argument @var{default} is present, it is returned; otherwise an
 error is signaled.
+NJFIXME - is this the same as module-symbol-binding?  If not, what is
+the difference?
 @end deffn
 
 @deffn procedure module-set! module name value
@@ -567,6 +575,8 @@
 the module bound to foo in some-root-module>
 @end example
 
+NJFIXME - can any module be used as a ROOT?
+
 @deffn procedure nested-ref root names
 Look up the variable identified by the symbol list @var{names}, starting
 in the module @var{root}.
@@ -624,6 +634,8 @@
 with the Guile distribution are installed under @code{(app modules)} as
 well.
 
+NJFIXME - so why do module install directories not include "app/modules"
+in their path? - or is that a silly question?
 
 @c ===================================================================
 
@@ -657,7 +669,7 @@
 
 @c ===================================================================
 
address@hidden Modules and Environments, Modules Miscallenea, Modules and 
Interfaces, Module Data Type
address@hidden Modules and Environments, Modules Miscellanea, Modules and 
Interfaces, Module Data Type
 @section Modules and Environments
 
 An environment belongs to a specific module, which can be determined by
@@ -669,8 +681,8 @@
 
 @c ===================================================================
 
address@hidden Modules Miscallenea,  , Modules and Environments, Module Data 
Type
address@hidden Modules Miscallenea
address@hidden Modules Miscellanea,  , Modules and Environments, Module Data 
Type
address@hidden Modules Miscellanea
 
 This chapter contains all miscellaneous information and procedure
 documentation which I have not been able to include elsewhere.  If
@@ -679,7 +691,8 @@
 
 @deffn procedure set-system-module! m s
 Set the @code{system-module} property of the module @var{m} to @var{s}.
address@hidden should be a module telling whehter @var{m} is a system module or
address@hidden should be a module - NJFIXME: not just a boolean? - 
+telling whether @var{m} is a system module or
 not.  System modules are treated specially in some cases, for example
 procedures defined in system modules are excluded from backtraces.
 FIXME: Is this last sentence true?




reply via email to

[Prev in Thread] Current Thread [Next in Thread]