[racket-dev] Attempted clarification for planet2 docs

On Jan 2, 2013, at 1:03 PM, Jay McCarthy wrote:

> Sounds fine. John's original language seems like that and is good to me.

Pushed, thanks.

John

> 
> 
> 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 --------------
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/20130102/20ee450e/attachment.p7s>