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

From: Ian Price <[email-masked]>
Date: Fri, 23 Dec 2011 23:53:51 +0000

Ian Hulin <[email-masked]> 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"