mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 11:50:28 +02:00
Code Activity

Edits for R6RS library implementation documentation, as suggested by

Browse source 
Ludovic Courtès.

* doc/ref/api-module.texi (R6RS Libraries): Wrap keywords variously in
  @code and @dfn forms; rewrite pointer to implicit phasing paper; add
  "Scheme Syntax" specification to @deffns.
This commit is contained in:
Julian Graham 2010-05-22 18:20:00 -04:00
parent 96640816c8
commit 43d6eb75f3
1 changed files with 17 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

35
doc/ref/api-modules.texi
View file

@ -783,15 +783,15 @@ expressions:
@subsection R6RS Libraries @subsection R6RS Libraries
In addition to the API described in the previous sections, you also In addition to the API described in the previous sections, you also
have the option to create modules using the portable ``library'' form have the option to create modules using the portable @code{library} form
described in R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The described in R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The
Revised^6 Report on the Algorithmic Language Scheme}), and to import Revised^6 Report on the Algorithmic Language Scheme}), and to import
libraries created in this format by other programmers. Guile's R6RS libraries created in this format by other programmers. Guile's R6RS
libraries implementation takes advantage of the flexibility built library implementation takes advantage of the flexibility built into the
into the module system by expanding the R6RS library form into a module system by expanding the R6RS library form into a corresponding
corresponding Guile ``define-module'' form that specifies equivalent Guile @code{define-module} form that specifies equivalent import and
import and export requirements and includes the same body export requirements and includes the same body expressions. The library
expressions. The library expression: expression:
@lisp @lisp
(library (mylib (1 2)) (library (mylib (1 2))
@ -809,7 +809,7 @@ is equivalent to the module definition:
@end lisp @end lisp
Central to the mechanics of R6RS libraries is the concept of import Central to the mechanics of R6RS libraries is the concept of import
and export ``levels,'' which control the visibility of bindings at and export @dfn{levels}, which control the visibility of bindings at
various phases of a library's lifecycle --- macros necessary to various phases of a library's lifecycle --- macros necessary to
expand forms in the library's body need to be available at expand expand forms in the library's body need to be available at expand
time; variables used in the body of a procedure exported by the time; variables used in the body of a procedure exported by the
@ -819,15 +819,14 @@ as a mechanism by which a library author can indicate that a
particular library import should take place at a particular phase particular library import should take place at a particular phase
with respect to the lifecycle of the importing library. with respect to the lifecycle of the importing library.
Guile's libraries implementation uses a technique called ``implicit Guile's libraries implementation uses a technique called
phasing'' (see @cite{Implicit Phasing for R6RS Libraries} by @dfn{implicit phasing} (first described by Abdulaziz Ghuloum and R.
Abdulaziz Ghuloum and R. Kent Dybvig), which allows the expander and Kent Dybvig), which allows the expander and compiler to automatically
compiler to automatically determine the necessary visibility of a determine the necessary visibility of a binding imported from another
binding imported from another library. As such, the @code{for} library. As such, the @code{for} sub-form described below is ignored by
sub-form described below is ignored by Guile (but may be required by Guile (but may be required by Schemes in which phasing is explicit).
Schemes in which phasing is explicit).
@deffn syntax library name (export export-spec ...) (import import-spec ...) body ... @deffn {Scheme Syntax} library name (export export-spec ...) (import import-spec ...) body ...
Defines a new library with the specified name, exports, and imports, Defines a new library with the specified name, exports, and imports,
and evaluates the specified body expressions in this library's and evaluates the specified body expressions in this library's
environment. environment.
@ -843,7 +842,7 @@ identifier @var{internal-name} names a variable defined or imported
by the library and @var{external-name} is the name by which the by the library and @var{external-name} is the name by which the
variable is seen by importing libraries. variable is seen by importing libraries.
Each @var{import-spec} must be either an ``import set'' (see below) Each @var{import-spec} must be either an @dfn{import set} (see below)
or must be of the form @code{(for import-set import-level ...)}, or must be of the form @code{(for import-set import-level ...)},
where each @var{import-level} is one of: where each @var{import-level} is one of:
@ -910,10 +909,10 @@ your libraries less portable to other Schemes.
@end deffn @end deffn
@deffn syntax import import-spec ... @deffn {Scheme Syntax} import import-spec ...
Import into the current environment the libraries specified by the Import into the current environment the libraries specified by the
given import specifications, where each @var{import-spec} takes the given import specifications, where each @var{import-spec} takes the
same form as in the ``library'' form described above. same form as in the @code{library} form described above.
@end deffn @end deffn