Re: [racket-users] Package layout in docs
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
> 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
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
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&iax=1&ia=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
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
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
> 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
> 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
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. Similarly, there are some drawbacks to allowing >
Re: [racket-users] Package layout in docs
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
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 | 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
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
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
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
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.