bug#10327: Please document include and include-from-path

bug#10327: Please document include and include-from-path

[Ian Hulin]

I think I know what these do, but could you include them in the docs,
and point out how differ from load and load-from-path.

Documentation something like this?

— Scheme Procedure: include filename

    Load filename and add its contents to a file currently being
compiled. Unlike /load/ its contents are not evaluated immediately.
The load paths are not searched.

— Scheme Procedure: include-from-path filename

    Locate /filename/ in the load paths, load /filename/ and add its
contents to a file currently being compiled. Unlike
/load-from-path/ its contents are not evaluated immediately.

bug#10327: Please document include and include-from-path

[Ian Price]

Ian Hulin <ian@hulin.org.uk> writes:

> I think I know what these do, but could you include them in the docs,
> and point out how differ from load and load-from-path.
>
> Documentation something like this?
>
> — Scheme Procedure: include filename
>
>     Load filename and add its contents to a file currently being
> compiled. Unlike /load/ its contents are not evaluated immediately.
> The load paths are not searched.
>
> — Scheme Procedure: include-from-path filename
>
>     Locate /filename/ in the load paths, load /filename/ and add its
> contents to a file currently being compiled. Unlike
> /load-from-path/ its contents are not evaluated immediately.

I agree, these should be documented, but I would stay away from using
the phrase 'load' in a description of these in case it is
confusing. Maybe "Adds the contents of the file, in place, at the point
of the 'include' macro use at macro expansion time"? Or am I being ever
so slightly patronising? 

-- 
Ian Price

"Programming is like pinball. The reward for doing it well is
the opportunity to do it again" - from "The Wizardy Compiled"

bug#10327: Please document include and include-from-path

[Andy Wingo]

Hello Ian & Ian :)

Thanks for the report.  I added some extensive docs.

    6.17.11 Local Inclusion
    -----------------------

    This section has discussed various means of linking Scheme code
    together: fundamentally, loading up files at run-time using `load' and
    `load-compiled'.  Guile provides another option to compose parts of
    programs together at expansion-time instead of at run-time.

     -- Scheme Syntax: include file-name
         Open FILE-NAME, at expansion-time, and read the Scheme forms that
         it contains, splicing them into the location of the `include',
         within a `begin'.

       If you are a C programmer, if `load' in Scheme is like `dlopen' in
    C, consider `include' to be like the C preprocessor's `#include'.  When
    you use `include', it is as if the contents of the included file were
    typed in instead of the `include' form.

       Because the code is included at compile-time, it is available to the
    macroexpander.  Syntax definitions in the included file are available to
    later code in the form in which the `include' appears, without the need
    for `eval-when'.  (*Note Eval When::.)

       For the same reason, compiling a form that uses `include' results in
    one compilation unit, composed of multiple files.  Loading the compiled
    file is one `stat' operation for the compilation unit, instead of `2*N'
    in the case of `load' (once for each loaded source file, and once each
    corresponding compiled file, in the best case).

       Unlike `load', `include' also works within nested lexical contexts.
    It so happens that the optimizer works best within a lexical context,
    because all of the uses of bindings in a lexical context are visible,
    so composing files by including them within a `(let () ...)' can
    sometimes lead to important speed improvements.

       On the other hand, `include' does have all the disadvantages of
    early binding: once the code with the `include' is compiled, no change
    to the included file is reflected in the future behavior of the
    including form.

       Also, the particular form of `include', which requires an absolute
    path, or a path relative to the current directory at compile-time, is
    not very amenable to compiling the source in one place, but then
    installing the source to another place.  For this reason, Guile provides
    another form, `include-from-path', which looks for the source file to
    include within a load path.

     -- Scheme Syntax: include-from-path file-name
         Like `include', but instead of expecting `file-name' to be an
         absolute file name, it is expected to be a relative path to search
         in the `%load-path'.

       `include-from-path' is more useful when you want to install all of
    the source files for a package (as you should!).  It makes it possible
    to evaluate an installed file from source, instead of relying on the
    `.go' file being up to date.


On Sat 24 Dec 2011 00:53, Ian Price <ianprice90@googlemail.com> writes:

> Or am I being ever so slightly patronising?

"Recursion and condescension"? :-)

  http://james-iry.blogspot.com/2009/05/brief-incomplete-and-mostly-wrong.html

Cheers,

Andy
-- 
http://wingolog.org/