[racket-dev] Attempted clarification for planet2 docs

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/dev/archive/attachments/20130102/1f201ee4/attachment-0001.html>