Re: [racket-users] Package layout in docs

[WarGrey Gyoudmon Ju]

On Tue, Jan 31, 2017 at 9:12 PM, Matthias Felleisen 
wrote:

>
> > On Jan 31, 2017, at 12:37 AM, WarGrey Gyoudmon Ju 
> wrote:
> >
> > Hello.
> >
> > This is one of the culture shocks that a new Racketeer would face, and
> so was I.
> > But this statement makes it clear to me: Racket is an operating system
> that pretend to a programming language;
> >
> > Yes, it may totally be a kind of over reading here.
>
>
> No, you’re not. See third principle of the Racket Manifesto
> (internalization) and the Revenge of the Son of the Lisp Machine.


Oh, I just forgot the Manifesto[1].
So why not give it an entry in the index page? just like "How to Program
Racket: a Style Guard";
or make a margin-note that links to it in the section "Naming and Designing
Packages"[2].

[1] http://www.ccs.neu.edu/home/matthias/manifesto/
[2]
https://docs.racket-lang.org/pkg/getting-started.html#%28part._.Naming_and_.Designing_.Packages%29

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Matthias Felleisen]

> On Jan 31, 2017, at 12:37 AM, WarGrey Gyoudmon Ju  
> wrote:
> 
> Hello.
> 
> This is one of the culture shocks that a new Racketeer would face, and so was 
> I.
> But this statement makes it clear to me: Racket is an operating system that 
> pretend to a programming language;
> 
> Yes, it may totally be a kind of over reading here.


No, you’re not. See third principle of the Racket Manifesto (internalization) 
and the Revenge of the Son of the Lisp Machine. 



> 
> Say, I do not care if a manual page is the one shipped with unix distribution 
> or installed by user, same to shell commands and shared objects, all entries 
> should globally unique.
> 
> Okay, the documentation system is a little different here, it can be provided 
> with a different front page, and obviously there is no way to satisfy all.
> Actually I am afraid of where to insert the entry of my package as well.
> 
> Of my preference, I would suggest putting status icons (or even emojis) in 
> front of every entry in the index page based on the ring system.


Everyone, 

I really like your brain storming here. This issue is something that definitely 
deserves discussion, and it would be terrific  if the community can come up 
with a near-consensus idea. In any case, I have put this topic on the agenda 
for our next coordination meeting where we will consider your ideas and discuss 
them. 

— Matthias

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Laurent]

I agree that in the TOC of the docs it would probably be better to separate
third party packages, maybe simply as a dedicated section or add
'(contributed package)' next to it.

On 30 Jan 2017 9:13 pm, "Matthew Butterick"  wrote:


On Jan 30, 2017, at 11:42 AM, Leif Andersen  wrote:

I don't think that the solution is to make core packages first class, and
community ones second class. That looses the spirit of what we're going for
here. But maybe we could have in our documentation a way for users to
select what packages they want to show up in search results. That way all
packages are equal here, and a person who wants to, say, only use core
packages, can get that.


To be fair, not all core packages are superior to their community variants.

For instance, `parser-tools` is core, yet has been called "strange and
klunky" compared to "modern Racket". [1] Whereas the `ragg` package is a
much nicer — dare I say more Rackety — interface to `parser-tools`.

So if Racket's policy is to let the boundary between core & community
remain porous, then it seems consistent to let these packages compete on an
even footing.


An alternative approach which probably takes less effort is to just have
two documentation pages. One for core packages, and one for community
packages. Obviously we should still make 3rd party packages feel like first
class build in stuff, but if we just host them at a different URL, that
might be enough to keep things clear.


Recently we added a Racket logo to the upper right of the public doc pages.
We could do something where this logo changed depending on whether the
package belonged to core or community or whatever. Then we wouldn't need to
actually cleave the docs into two websites (which IMO is
counterproductive).

Later we can get to Yelp-style star reviews: "Meh, I've experienced better
mutable vectors."



[1] https://groups.google.com/d/msg/racket-dev/pVcE3hdsfbM/U8dBBcPfCAAJ

-- 
You received this message because you are subscribed to the Google Groups
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Ethan Estrada]

Putting the logo in the corner or line under the title solves only half of
the problem, IMHO. Yes, you can determine which packages are core and which
are community, however you still can't differentiate at a glance which is
which. Although it is an improvement, it is still a pain in practice since
one needs to check each link to see the provenance of a package/library.
Where there are clearly a few different packages for a given thing, this
can cost time and aggravation. For instance, there are two or three
packages for parsing html, two for json, two or three for OpenGL and so
forth. Which is a core library? Which is a toy that someone made to explore
that particular domain and try out the package system? Which is a
production tool that someone built to solve an actual problem they were
facing?

Another possible way might be to have each item have effectively a bullet
point on the main page, but the bullet point is an icon; the stylized
Racket Lambda icon for core packages and a different one for community
supplied ones. For instance, a stylized group of people like here:

https://duckduckgo.com/?q=community+icon=1=images

The fact that community generated packages are on the front docs page still
gives them equal status, even while clearly indicating their origin.

To address Matthew's point of some community packages being more idiomatic
or easier to work with than some core racket libraries, I don't think
obfuscating their origin necessarily helps users discover alternative
packages more easily. Most often, users (in any software ecosystem) will
learn that one package is easier/better/faster/friendlier by asking around
on mailing lists, chat groups or user forums. If people don't ask in those
places, then it essentially becomes a coin toss. "Which package do I try
out first?" Then they will either stick with the first one they try because
it is good enough, or they will go to the next one because the first one
wasn't good enough. With differentiating the packages, it takes out the
coin toss which takes time and energy. Yes, I may end up using a community
provided package because the core package isn't quite up to snuff for my
needs, but at least I didn't need to wonder which one I should try first.
As it is, a new user is flying somewhat blind.

Also, +1 what Lehi said; more than once I have tried to `(require)`
something, thinking it was part of the standard install and then been
barked at because I need to go out and fetch the package first.

--
Ethan Estrada | CTO & COO
M: 801-669-1598 | E: et...@metapipe.com
The Startup Building | 560 S 100 W STE 1, Provo UT 84601-4570
MetaPipe.com


Making the Cloud easy to use for VFX and Animation

On Mon, Jan 30, 2017 at 3:02 PM, Dupéron Georges <
jahvascriptman...@gmail.com> wrote:

> Le lundi 30 janvier 2017 22:13:57 UTC+1, Matthew Butterick a écrit :
> > Recently we added a Racket logo to the upper right of the public doc
> pages. We could do something where this logo changed depending on whether
> the package belonged to core or community or whatever. Then we wouldn't
> need to actually cleave the docs into two websites (which IMO is
> counterproductive).
>
> I agree with Matthew Butterick that splitting the docs into two websites
> would be counterproductive. As a user, I don't want to have to remember
> whether this package happens to be in main-distribution or not, and look up
> one website or the other. The same applies when searching for a
> functionality: I would rather avoid having to search on two different
> websites.
>
> The logo idea seems like a nice compromise.
>
> Another possibility would be to change the packages so that they display
> somewhere below the title "Part of the community package foo", "Part of the
> main Racket distribution" or "Part of the minimal Racket distribution". As
> far as I can tell, this would require cooperation from the packages
> (modifying the scribble files), unless Scribble forcefully inserts the text
> (like the "v.6.8" above the title).
>
> --
> You received this message because you are subscribed to a topic in the
> Google Groups "Racket Users" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/
> topic/racket-users/bDkB2H8VO_I/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Leif Andersen]

So, I really don't care how it work. Logo is fine, seperate website is
fine. Checkboxes that lets users say what packages come in are fine.
Yelp reviews are fine (although if we go down that route can we also
add Edit buttons. ;) )

My only concern is that at the moment, anyone can publish something
that very much looks and feels like it was either done by, or
supported by, PLT Design Inc. Which is a potentially dangerous thing.
All of the above solutions y'all suggested solve that issue. ;)

(Oh also Matthew, I completely agree with you. There are some pretty
awesome community built packages which I like way more than the one in
the core distribution.)

~Leif Andersen


On Mon, Jan 30, 2017 at 5:02 PM, Dupéron Georges
 wrote:
> Le lundi 30 janvier 2017 22:13:57 UTC+1, Matthew Butterick a écrit :
>> Recently we added a Racket logo to the upper right of the public doc pages. 
>> We could do something where this logo changed depending on whether the 
>> package belonged to core or community or whatever. Then we wouldn't need to 
>> actually cleave the docs into two websites (which IMO is counterproductive).
>
> I agree with Matthew Butterick that splitting the docs into two websites 
> would be counterproductive. As a user, I don't want to have to remember 
> whether this package happens to be in main-distribution or not, and look up 
> one website or the other. The same applies when searching for a 
> functionality: I would rather avoid having to search on two different 
> websites.
>
> The logo idea seems like a nice compromise.
>
> Another possibility would be to change the packages so that they display 
> somewhere below the title "Part of the community package foo", "Part of the 
> main Racket distribution" or "Part of the minimal Racket distribution". As 
> far as I can tell, this would require cooperation from the packages 
> (modifying the scribble files), unless Scribble forcefully inserts the text 
> (like the "v.6.8" above the title).

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Dupéron Georges]

Le lundi 30 janvier 2017 22:13:57 UTC+1, Matthew Butterick a écrit :
> Recently we added a Racket logo to the upper right of the public doc pages. 
> We could do something where this logo changed depending on whether the 
> package belonged to core or community or whatever. Then we wouldn't need to 
> actually cleave the docs into two websites (which IMO is counterproductive). 

I agree with Matthew Butterick that splitting the docs into two websites would 
be counterproductive. As a user, I don't want to have to remember whether this 
package happens to be in main-distribution or not, and look up one website or 
the other. The same applies when searching for a functionality: I would rather 
avoid having to search on two different websites.

The logo idea seems like a nice compromise.

Another possibility would be to change the packages so that they display 
somewhere below the title "Part of the community package foo", "Part of the 
main Racket distribution" or "Part of the minimal Racket distribution". As far 
as I can tell, this would require cooperation from the packages (modifying the 
scribble files), unless Scribble forcefully inserts the text (like the "v.6.8" 
above the title).

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Matthew Butterick]

> On Jan 30, 2017, at 11:42 AM, Leif Andersen  wrote:
> 
> I don't think that the solution is to make core packages first class, and 
> community ones second class. That looses the spirit of what we're going for 
> here. But maybe we could have in our documentation a way for users to select 
> what packages they want to show up in search results. That way all packages 
> are equal here, and a person who wants to, say, only use core packages, can 
> get that.

To be fair, not all core packages are superior to their community variants. 

For instance, `parser-tools` is core, yet has been called "strange and klunky" 
compared to "modern Racket". [1] Whereas the `ragg` package is a much nicer — 
dare I say more Rackety — interface to `parser-tools`. 

So if Racket's policy is to let the boundary between core & community remain 
porous, then it seems consistent to let these packages compete on an even 
footing.


> An alternative approach which probably takes less effort is to just have two 
> documentation pages. One for core packages, and one for community packages. 
> Obviously we should still make 3rd party packages feel like first class build 
> in stuff, but if we just host them at a different URL, that might be enough 
> to keep things clear.

Recently we added a Racket logo to the upper right of the public doc pages. We 
could do something where this logo changed depending on whether the package 
belonged to core or community or whatever. Then we wouldn't need to actually 
cleave the docs into two websites (which IMO is counterproductive). 

Later we can get to Yelp-style star reviews: "Meh, I've experienced better 
mutable vectors."



[1] https://groups.google.com/d/msg/racket-dev/pVcE3hdsfbM/U8dBBcPfCAAJ

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Lehi Toskin]

> An alternative approach which probably takes less effort is to just have two 
> documentation pages. One for core packages, and one for community packages. 
> Obviously we should still make 3rd party packages feel like first class build 
> in stuff, but if we just host them at a different URL, that might be enough 
> to keep things clear.

+1 - I really like that the documentation generated for any given package looks 
the same as another, but there have been some times where I've searched through 
the documentation and found a package where it was not obvious it was 
user-submitted and got confused when Racket complained that package wasn't 
installed already.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Leif Andersen]

FWIW, I have to support Ethan here. (At least a little bit).

I really how user installed packages (and collections) in Racket feel like
first class citizens. Its very nice, both that its rewarding when I make a
new package, but also in terms of searching for documentation and whatnot.

However, there is something to be said about having them show up as results
on the _official docs_ on our webpage.

Anyone can upload a package to pkgs.racket-lang.org and, provided that it
compiles, we'll display the content on our webpage as if it was a first
class thing.

While we have a sandbox to prevent certain classes of technical malicious
attacks we don't really have much in place (other than the community) for
social engineering based attacks.

For example, I could make a package that looks normal, acts normal, and
most of the docs are normal, but in the docs it links to some malicious
page, or has misleading content. Well, now we just not only gave this
package a platform, but we gave it a platform that looks like we 100%
endorse it, because its mixed seamlessly in with the API that ships with
the core distribution.

I don't think that the solution is to make core packages first class, and
community ones second class. That looses the spirit of what we're going for
here. But maybe we could have in our documentation a way for users to
select what packages they want to show up in search results. That way all
packages are equal here, and a person who wants to, say, only use core
packages, can get that.

An alternative approach which probably takes less effort is to just have
two documentation pages. One for core packages, and one for community
packages. Obviously we should still make 3rd party packages feel like first
class build in stuff, but if we just host them at a different URL, that
might be enough to keep things clear.

just some thoughts anyway.


~Leif Andersen

On Sun, Jan 29, 2017 at 3:48 PM, Ethan Estrada 
wrote:

> Curse my sausage fingers! That last send was unintentional. I've deleted
> it from the online Google Groups forum for the sake of future subscribers.
>
> I can understand wanting to minimize the distinction and in some ways make
> all core language, standard libraries, and community libraries equal.
>
> For me the issue is software maintenance. If I'm building something that
> needs functionality from an external library, I'm more likely to choose a
> library from the standard install if one exists. I can be reasonably
> certain it will be supported for a long time into the future, and if it
> ever ceases to be supported it will likely be gracefully deprecated over
> the course of a few releases. Neither of those points are guaranteed, but I
> think they are reasonable assumptions to make.
>
> Also, to some extent there already is a distinction in the documentation.
> There is the section "Racket Language and Core Libraries", and then there
> is everything else. However, the libraries from the 'base' package and
> other shipped packages are sprinkled into the "everything else" docs and
> not all the shipped packages are listed under "Racket Language and Core
> Libraries". So it makes things murky.
>
> A possible compromise may be to have the top level page of http://
> docs.racket-lang.org/ remain the same, but have a small link/page under
> http://docs.racket-lang.org/reference/ page that lists the links to all
> the packages/libraries/collections that are shipped by default with Racket.
> The pages that the links point to would all still live where they always
> have and still be listed at the top level http://docs.racket-lang.org/
> the same way they already are. That way there is some centralized place to
> figure out what ships with racket without mucking around the filesystem
> after install, or checking on each link on http://docs.racket-lang.org/
> to see if the package it requires from is 'base' or something else core to
> the install.
>
> To Stephen, thanks for sharing the articles from Eric Raymond. It made me
> think maybe I'm not just a crazy guy on the street corner wearing a burlap
> sack and a tin foil hat declaring the end of the world. Or, at the very
> least, I'm not alone on the street corner :) .
>
> --
> Ethan Estrada
>
> On Jan 29, 2017 06:45, "Matthew Flatt"  wrote:
>
> At Sat, 28 Jan 2017 22:51:43 -0800 (PST), Ethan Estrada wrote:
> > My only real beef with the Racket docs are the layout of packages;
> > there is no clear distinction between docs for standard library items
> > and docs for community provided libs.
>
> That's intentional. I'd say that the absence of a line that
> distinguishes "Racket" from "not Racket" at the package level is an
> extrapolation of our goal to avoid a line between the "language" and
> "library" at the level of a module.
>
> There are certainly some drawbacks to allowing any old module to add
> new constructs to the programming language, but we think the benefits
> outweigh the drawbacks. 

Re: [racket-users] Package layout in docs

[Ethan Estrada]

Curse my sausage fingers! That last send was unintentional. I've deleted it
from the online Google Groups forum for the sake of future subscribers.

I can understand wanting to minimize the distinction and in some ways make
all core language, standard libraries, and community libraries equal.

For me the issue is software maintenance. If I'm building something that
needs functionality from an external library, I'm more likely to choose a
library from the standard install if one exists. I can be reasonably
certain it will be supported for a long time into the future, and if it
ever ceases to be supported it will likely be gracefully deprecated over
the course of a few releases. Neither of those points are guaranteed, but I
think they are reasonable assumptions to make.

Also, to some extent there already is a distinction in the documentation.
There is the section "Racket Language and Core Libraries", and then there
is everything else. However, the libraries from the 'base' package and
other shipped packages are sprinkled into the "everything else" docs and
not all the shipped packages are listed under "Racket Language and Core
Libraries". So it makes things murky.

A possible compromise may be to have the top level page of http://
docs.racket-lang.org/ remain the same, but have a small link/page under
http://docs.racket-lang.org/reference/ page that lists the links to all the
packages/libraries/collections that are shipped by default with Racket. The
pages that the links point to would all still live where they always have
and still be listed at the top level http://docs.racket-lang.org/ the same
way they already are. That way there is some centralized place to figure
out what ships with racket without mucking around the filesystem after
install, or checking on each link on http://docs.racket-lang.org/ to see if
the package it requires from is 'base' or something else core to the
install.

To Stephen, thanks for sharing the articles from Eric Raymond. It made me
think maybe I'm not just a crazy guy on the street corner wearing a burlap
sack and a tin foil hat declaring the end of the world. Or, at the very
least, I'm not alone on the street corner :) .

--
Ethan Estrada

On Jan 29, 2017 06:45, "Matthew Flatt"  wrote:

At Sat, 28 Jan 2017 22:51:43 -0800 (PST), Ethan Estrada wrote:
> My only real beef with the Racket docs are the layout of packages;
> there is no clear distinction between docs for standard library items
> and docs for community provided libs.

That's intentional. I'd say that the absence of a line that
distinguishes "Racket" from "not Racket" at the package level is an
extrapolation of our goal to avoid a line between the "language" and
"library" at the level of a module.

There are certainly some drawbacks to allowing any old module to add
new constructs to the programming language, but we think the benefits
outweigh the drawbacks. Similarly, there are some drawbacks to allowing
any old package to have the same status as the base system, but I
believe in the benefits.

In both cases, it's important that programmers have control over what
is used and what isn't used. The module system enforces boundaries so
that a module added to a program can't have an arbitrary effect on
other modules in the program. Similarly, the package system is intended
to give the programmer control over what packages are installed and how
they are installed.

I'm not objecting to improvement here --- just trying to clarify why
the current organization is like that.

Also, I'd concede that we have a notion of "main distribution", which
identifies a set of packages that are included in the Racket installers
at racket-lang.org. That's a useful concept, but I see it as a
compromise, and I'm reluctant to reflect that distinction in the
documentation.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Stephen Chang]

I like the current structure of the docs but Ethan's comments reminded
of recent blog posts by Eric Raymond (of "Cathedral and the Bazaar"
fame), who surprisingly advocates against "swarm design". The posts
are about Rust but maybe it's something to keep in mind if the package
system gets much large.

[1]: http://esr.ibiblio.org/?p=7294
[2]: http://esr.ibiblio.org/?p=7303

On Sun, Jan 29, 2017 at 8:45 AM, Matthew Flatt  wrote:
> At Sat, 28 Jan 2017 22:51:43 -0800 (PST), Ethan Estrada wrote:
>> My only real beef with the Racket docs are the layout of packages;
>> there is no clear distinction between docs for standard library items
>> and docs for community provided libs.
>
> That's intentional. I'd say that the absence of a line that
> distinguishes "Racket" from "not Racket" at the package level is an
> extrapolation of our goal to avoid a line between the "language" and
> "library" at the level of a module.
>
> There are certainly some drawbacks to allowing any old module to add
> new constructs to the programming language, but we think the benefits
> outweigh the drawbacks. Similarly, there are some drawbacks to allowing
> any old package to have the same status as the base system, but I
> believe in the benefits.
>
> In both cases, it's important that programmers have control over what
> is used and what isn't used. The module system enforces boundaries so
> that a module added to a program can't have an arbitrary effect on
> other modules in the program. Similarly, the package system is intended
> to give the programmer control over what packages are installed and how
> they are installed.
>
> I'm not objecting to improvement here --- just trying to clarify why
> the current organization is like that.
>
> Also, I'd concede that we have a notion of "main distribution", which
> identifies a set of packages that are included in the Racket installers
> at racket-lang.org. That's a useful concept, but I see it as a
> compromise, and I'm reluctant to reflect that distinction in the
> documentation.
>
> --
> You received this message because you are subscribed to the Google Groups 
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Ethan Estrada]

--
Ethan Estrada | CTO & COO
M: 801-669-1598 | E: et...@metapipe.com
The Startup Building | 560 S 100 W STE 1
(sent from my phone)

On Jan 29, 2017 06:45, "Matthew Flatt"  wrote:

At Sat, 28 Jan 2017 22:51:43 -0800 (PST), Ethan Estrada wrote:
> My only real beef with the Racket docs are the layout of packages;
> there is no clear distinction between docs for standard library items
> and docs for community provided libs.

That's intentional. I'd say that the absence of a line that
distinguishes "Racket" from "not Racket" at the package level is an
extrapolation of our goal to avoid a line between the "language" and
"library" at the level of a module.

There are certainly some drawbacks to allowing any old module to add
new constructs to the programming language, but we think the benefits
outweigh the drawbacks. Similarly, there are some drawbacks to allowing
any old package to have the same status as the base system, but I
believe in the benefits.

In both cases, it's important that programmers have control over what
is used and what isn't used. The module system enforces boundaries so
that a module added to a program can't have an arbitrary effect on
other modules in the program. Similarly, the package system is intended
to give the programmer control over what packages are installed and how
they are installed.

I'm not objecting to improvement here --- just trying to clarify why
the current organization is like that.

Also, I'd concede that we have a notion of "main distribution", which
identifies a set of packages that are included in the Racket installers
at racket-lang.org. That's a useful concept, but I see it as a
compromise, and I'm reluctant to reflect that distinction in the
documentation.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Deren Dohoda]

Honestly I've never even thought about this. I just look at the "require"
form at the top of the docs. Since I always use racket/base as my main
language, everything feels like extra.

On Sun, Jan 29, 2017 at 8:45 AM, Matthew Flatt  wrote:

> At Sat, 28 Jan 2017 22:51:43 -0800 (PST), Ethan Estrada wrote:
> > My only real beef with the Racket docs are the layout of packages;
> > there is no clear distinction between docs for standard library items
> > and docs for community provided libs.
>
> That's intentional. I'd say that the absence of a line that
> distinguishes "Racket" from "not Racket" at the package level is an
> extrapolation of our goal to avoid a line between the "language" and
> "library" at the level of a module.
>
> There are certainly some drawbacks to allowing any old module to add
> new constructs to the programming language, but we think the benefits
> outweigh the drawbacks. Similarly, there are some drawbacks to allowing
> any old package to have the same status as the base system, but I
> believe in the benefits.
>
> In both cases, it's important that programmers have control over what
> is used and what isn't used. The module system enforces boundaries so
> that a module added to a program can't have an arbitrary effect on
> other modules in the program. Similarly, the package system is intended
> to give the programmer control over what packages are installed and how
> they are installed.
>
> I'm not objecting to improvement here --- just trying to clarify why
> the current organization is like that.
>
> Also, I'd concede that we have a notion of "main distribution", which
> identifies a set of packages that are included in the Racket installers
> at racket-lang.org. That's a useful concept, but I see it as a
> compromise, and I'm reluctant to reflect that distinction in the
> documentation.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Package layout in docs

[Matthew Flatt]

At Sat, 28 Jan 2017 22:51:43 -0800 (PST), Ethan Estrada wrote:
> My only real beef with the Racket docs are the layout of packages;
> there is no clear distinction between docs for standard library items
> and docs for community provided libs.

That's intentional. I'd say that the absence of a line that
distinguishes "Racket" from "not Racket" at the package level is an
extrapolation of our goal to avoid a line between the "language" and
"library" at the level of a module.

There are certainly some drawbacks to allowing any old module to add
new constructs to the programming language, but we think the benefits
outweigh the drawbacks. Similarly, there are some drawbacks to allowing
any old package to have the same status as the base system, but I
believe in the benefits.

In both cases, it's important that programmers have control over what
is used and what isn't used. The module system enforces boundaries so
that a module added to a program can't have an arbitrary effect on
other modules in the program. Similarly, the package system is intended
to give the programmer control over what packages are installed and how
they are installed.

I'm not objecting to improvement here --- just trying to clarify why
the current organization is like that.

Also, I'd concede that we have a notion of "main distribution", which
identifies a set of packages that are included in the Racket installers
at racket-lang.org. That's a useful concept, but I see it as a
compromise, and I'm reluctant to reflect that distinction in the
documentation.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[racket-users] Package layout in docs

[Ethan Estrada]

I have been reading the docs a lot lately as I have been building a couple 
internal tools at my work using Racket. It has been awesome.

The docs are some of the best I have used, second only to maybe the Python 
standard docs (for reasons largely unrelated to what I'm posting about here). 
My only real beef with the Racket docs are the layout of packages; there is no 
clear distinction between docs for standard library items and docs for 
community provided libs. I like that all the docs are centralized, even for 
community provided packages. It's also great that packages are broken up by 
category. However, it is frustrating that the difference between stdlib 
packages and community packages can't be differentiated at a glance. One has to 
first dive into the docs for a particular package to determine where it is 
from. It would be nice to have the distinction clearly separated on the main 
docs.racket-lang.org page.

Maybe there is something I am missing, but as someone who is relatively new to 
the ecosystem, I can say it isn't clear at first blush how to differentiate. In 
fact, I am still not totally clear what all is included with a racket install. 
The only sure-fire way I know how to check is by traversing the installed 
"collects" and "share/pkg" directories.

For instance, one way to separate packages on the docs page might be:

Minimal Racket libs:
  * A
  * B
  * C

Full Racket libs (in addition to minimal Racket):
  * D
  * E
  * F

Community Supported libs:
  * G
  * H
  * I

So, I guess my question is threefold:

1. Is there some way to differentiate that I am missing?

2. If there isn't, does this bother anyone else, or is it just me?

3. If this is an actual issue, how might I go about rectifying it?  I am 
happy to submit code to change the behavior of the doc generation. Some 
pointers as to where to look would be helpful in that case. The only place I 
have found that seems to be right is in the pkg-build repo here:

https://github.com/racket/pkg-build/blob/master/extract-doc.rkt

Other than that, I am not yet clear how/when the extracted docs are posted 
to the docs page.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[racket-users] Package layout in docs

[Ethan Estrada]

I have been reading the docs a lot lately as I have been building a couple 
internal tools at my work using Racket. It has been awesome.

The docs are some of the best I have used, second only to maybe the Python 
standard docs (for reasons largely unrelated to what I'm posting about here). 
My only real beef with the Racket docs are the layout of packages; there is no 
clear distinction between docs for standard library items and docs for 
community provided libs. I like that all the docs are centralized, even for 
community provided packages. It's also great that packages are broken up by 
category. However, it is frustrating that the difference between stdlib 
packages and community packages can't be differentiated at a glance. One has to 
first dive into the docs for a particular package to determine where it is 
from. It would be nice to have the distinction clearly separated on the main 
docs.racket-lang.org page.

Maybe there is something I am missing, but as someone who is relatively new to 
the ecosystem, I can say it isn't clear at first blush how to differentiate. In 
fact, I am still not totally clear what all is included with a racket install. 
The only sure-fire way I know how to check is by traversing the installed 
"collects" and "share/pkg" directories.

For instance, one way to separate packages on the docs page might be:

Minimal Racket libs:
  * A
  * B
  * C

Full Racket libs (in addition to minimal Racket):
  * D
  * E
  * F

Community Supported libs:
  * G
  * H
  * I

So, I guess my question is threefold:

1. Is there some way to differentiate that I am missing?

2. If there isn't, does this bother anyone else, or is it just me?

3. If this is an actual issue, how might I go about rectifying it?  I am 
happy to submit code to change the behavior of the doc generation. Some 
pointers as to where to look would be helpful in that case. The only place I 
have found that seems to be right is in the pkg-build repo here:

https://github.com/racket/pkg-build/blob/master/extract-doc.rkt

Other than that, I am not yet clear how/when the extracted docs are posted 
to the docs page.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.