[racket-dev] Attempted clarification for planet2 docs

On Jan 3, 2013, at 6:36 AM, Matthew Flatt wrote:

> I went to fix a typo (`tech' to `racket') and ended up moving and
> tweaking the text. I hope the changes are ok.
> 
> I like the way the example distinguishes the package name, collection
> name, and library name, and so I added a sentence to explicitly note
> that `require' lines don't refer to packages. Then again, it also
> seemed worth nothing that a package will often supply a collection
> whose name matches the package.

Many thanks. My intent was to provide a starting point, and to encourage others to fill in details.

John

> 
> At Wed, 2 Jan 2013 14:03:45 -0700, Jay McCarthy wrote:
>> Sounds fine. John's original language seems like that and is good to me.
>> 
>> 
>> On Wed, Jan 2, 2013 at 1:59 PM, Carl Eastlund <cce at ccs.neu.edu> wrote:
>> 
>>> It doesn't need to be phrased as a comparison to Planet1, but it can be
>>> given as a reassurance that this "package system" thingy does not add any
>>> baggage to require lines.
>>> 
>>> Carl Eastlund
>>> 
>>> 
>>> On Wed, Jan 2, 2013 at 3:49 PM, Jay McCarthy <jay.mccarthy at gmail.com>wrote:
>>> 
>>>> I agree in that context that it is useful as a part of the "What's
>>>> different about Planet 2?" And it's there (question 6).
>>>> 
>>>> But, in the context of a new Racket user learning about packages, I don't
>>>> see a reason to add the baggage of how it's different than some system
>>>> they've never used.
>>>> 
>>>> Jay
>>>> 
>>>> 
>>>> On Wed, Jan 2, 2013 at 1:40 PM, Carl Eastlund <cce at ccs.neu.edu> wrote:
>>>> 
>>>>> 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
>>>>>> 
>>>>>> 
>>>>> 
>>>> 
>>>> 
>>>> --
>>>> 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
>>>> 
>>> 
>>> 
>> 
>> 
>> -- 
>> 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
> _________________________
>  Racket Developers list:
>  http://lists.racket-lang.org/dev

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4370 bytes
Desc: not available
URL: <http://lists.racket-lang.org/dev/archive/attachments/20130103/563b9b5a/attachment.p7s>