[racket-dev] Attempted clarification for planet2 docs

Looks great to me.


On Thu, Jan 3, 2013 at 7:36 AM, Matthew Flatt <mflatt at cs.utah.edu> 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.
>
> 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
>



-- 
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/20130103/b31d512a/attachment-0001.html>