[racket-dev] Attempted clarification for planet2 docs

There _is_ reason to think these modules are different, because they were
different in Planet1.  I've had to remind myself several times that Planet2
packages don't have special require forms, and that's just during
discussions -- I haven't even been writing code with them yet.  Clarifying
that Planet2 simplifies the require lines, and makes user packages on a
peer level with built-in collections, is a useful thing to put early on in
the Planet2 docs.

Carl Eastlund


On Wed, Jan 2, 2013 at 3:27 PM, Jay McCarthy <jay.mccarthy at gmail.com> wrote:

> The documentation already says "A package is a set of modules for some
> number of collections." And there's no reason to think that these modules
> are different from other modules, so I don't see why we need to point out
> that they are required like all other modules are.
>
> If you think it's very confusing, then feel free to push the commit with
> two small changes:
>
> 1. The docs don't use the term "planet2", so just say "the Racket package
> manager"
>
> 2. Consider using the same examples from the rest of the docs (such as
> data/matrix from tic-tac-toe)
>
> Jay
>
>
>
> On Wed, Jan 2, 2013 at 12:30 PM, John Clements <clements at brinckerhoff.org>wrote:
>
>> As I was trying to assembly my first planet2 package, I found myself
>> wondering how exactly to 'require' modules associated with planet2
>> packages. My initial assumption (require them like any other collection
>> containing modules) turned out to be correct, but there was a period when I
>> doubted this, and I think it should be documented.
>>
>> Below is a proposed doc change; I'll commit it if you like it, or abandon
>> it if not. I'm including the (git format-patch) text and also attaching it
>> as a file.
>>
>> John
>>
>>
>>
>> >From d3f72c47820effb240532c518378dc9709d69600 Mon Sep 17 00:00:00 2001
>> From: John Clements <clements at racket-lang.org>
>> Date: Tue, 1 Jan 2013 10:40:40 -0800
>> Subject: [PATCH] added docs on requiring planet2 modules
>>
>> ---
>>  collects/planet2/scribblings/planet2.scrbl |   14 ++++++++++++++
>>  1 files changed, 14 insertions(+), 0 deletions(-)
>>
>> diff --git a/collects/planet2/scribblings/planet2.scrbl
>> b/collects/planet2/scribblings/planet2.scrbl
>> index e9e565a..81d6e58 100644
>> --- a/collects/planet2/scribblings/planet2.scrbl
>> +++ b/collects/planet2/scribblings/planet2.scrbl
>> @@ -200,6 +200,20 @@ imply a change in the @tech{checksum}.
>>
>>  @section{Using Packages}
>>
>> +Modules installed using planet2 may be @tech{require}d like any other
>> +modules. For instance, if the package @pkgname{recipes} contains
>> +the module file  @filepath{vegan/fruitsalad.rkt}, then package users
>> +who have this package installed may evaluate
>> +
>> + at racketblock[(require vegan/fruitsalad)]
>> +
>> +...to require this module.
>> +
>> +@; ----------------------------------------
>> +
>> + at section{Managing Packages}
>> +
>> +
>>  The Racket package manager has two user interfaces: a command line
>> @exec{raco}
>>  sub-command and a library. They have the exact same capabilities, as
>>  the command line interface invokes the library functions and
>> --
>> 1.7.7.5 (Apple Git-26)
>>
>>
>>
>
>
> --
> Jay McCarthy <jay at cs.byu.edu>
> Assistant Professor / Brigham Young University
> http://faculty.cs.byu.edu/~jay
>
> "The glory of God is Intelligence" - D&C 93
>
> _________________________
>   Racket Developers list:
>   http://lists.racket-lang.org/dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/dev/archive/attachments/20130102/71c71a4e/attachment.html>