Re: [DOCS] Documentation tools
[EMAIL PROTECTED] (Dan Sugalski) writes: [...] It's an ongoing fight between the go get the libs and install them folks and the self-contained distribution folks. I'm in the latter category. :) As Larry said, self-contained is good for users. For developers (and CVS) go get the libs is appropriate. A script can assemble the user distribution(s) with pre-defined versions of the libs to include. - ask -- ask bjoern hansen, http://www.askbjoernhansen.com/ !try; do();
Re: [DOCS] Documentation tools
At 4:45 PM +0100 3/4/04, Michael Scott wrote: On 4 Mar 2004, at 15:51, Dan Sugalski wrote: [...] I'd like to remove non-modified, non-parrot Perl modules from lib and install them via CPAN.pm. No. Sorry, definitely not. Parrot's config isn't going to install perl modules off the 'net any more than it's going to run apt-get on systems that support it. We either provide it or do without. Which is how I originally looked at it when I added Pod::Simple. But then Robert asked why are we including CPAN modules that we are not likely to change into the parrot repository?, and Leo suggested the prominent notes approach, which left me with the impression that this was something that had to be dealt with. It's an ongoing fight between the go get the libs and install them folks and the self-contained distribution folks. I'm in the latter category. :) So, do I just leave Pod::Simple there? Depends on when Pod::Simple showed up in the standard perl distribution. If it can be reasonably expected to be there and working back to 5.6.0, *and* we gracefully fail if it's not there, we can leave it out. If not, it stays in. -- Dan --it's like this--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: [DOCS] Documentation tools
At 11:49 AM -0800 3/4/04, Robert Spier wrote: I'd like to remove non-modified, non-parrot Perl modules from lib and install them via CPAN.pm. No. Sorry, definitely not. Parrot's config isn't going to install perl modules off the 'net any more than it's going to run apt-get on systems that support it. We either provide it or do without. Huh? Dan, what are you smoking? Real Good Crack. And I'm going to keep on smoking it. What we have right now is essentially a user distribution of Parrot. It's self-contained. It's a pain. It *should* be a pain--that pain is what keeps the dependency count down. The rule, as it stands (and will continue to stand) is that anything that's needed to get a parrot build from distribution to installable executable ships with parrot. Period. Things that *aren't* needed don't have to be in the tarball, and its up to the source pumpking to decide if it's acceptable. Rebuilding the grammar source for IMCC requires lex and yacc. We don't ship 'em, you have to have them installed, that's fine. We don't *need* them to build parrot from a distribution or checkout. I said way back when that the only thing anyone will need to build parrot from a release is a C compiler and *maybe* a make tool. (ICU may require us to open that up to a C++ compiler too) That's it, and it hasn't changed. Unless, of course, you'd rather we generally distribute binaries rather than source. That'd certainly make our lives a lot easier, but I'd really rather not go that route. -- Dan --it's like this--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: [DOCS] Documentation tools
On 6 Mar 2004, at 05:31, Robert Spier wrote: [...] The problem isn't today. It's the trend and next month, when someone decides they need to add some other module, and has a precedent to follow. Then, suddenly we end up with 30 different modules included in our distribution, each one changed slightly from the CPAN one. Dual-lifed modules that live with perl5 are hard enough. I shoved Pod::Simple in because I had problems with the Pod modules in the Perl distribution and the people on pod-people assured me Pod::Simple was the way to go. It was the soft option, i wanted people to be able to build the html docs easily, and I took the existence of the other modules in lib as examples of how to go about it. So, yes, precedent is the problem. Which is why I'd prefer if we could decide what the rule is and apply it to Pod::Simple etc* now, so that it sets the correct precedent. I have held off modifying it, so that it can be removed if necessary. Also, Dan, is it inherently bad to to install perl modules off the 'net, or, just bad for Parrot's config to do it? Would it be acceptable for write_docs.pl to do it? Or, do you mean that the distribution has to be complete in itself, so that it can be installed off a cd on a network-less box and run? Lastly, if we use Leo's prominent notes approach, is that note in the end not just going to be: To install the additional Perl modules required by Parrot run the following command in a shell: perl -MCPAN -e 'CPAN::Shell-install(Parrot::Bundle) Mike [*] Class::Struct has been patched to work with 5.005_03. Digest::Perl::MD5 is unmodified except where I changed the bang perl line. Parse::Parse::RecDescent has been modified for perl6. Pod::Simple unmodified. Test::More, only Test::Builder has been modified. Text::Balanced is unmodified.
Re: [DOCS] Documentation tools
On Mar 4, 2004, at 7:50 PM, Robert Spier wrote: IMHO, the releases better include everything necessary to build the application, within reason. Consistency and simplicity counts for a lot. Why create headaches we don't need? within reason. Thats where we're way off right now. Let's keep a bit of perspective here. The non-Parrot:: contents of lib accounts for only 4.6% of the non-ICU content (and only 1.5% if you count ICU in the total size). It's difficult to see that as unreasonable, or as bloat. JEff
Re: [DOCS] Documentation tools
within reason. Thats where we're way off right now. Let's keep a bit of perspective here. The non-Parrot:: contents of lib accounts for only 4.6% of the non-ICU content (and only 1.5% if you count ICU in the total size). It's difficult to see that as unreasonable, or as bloat. The problem isn't today. It's the trend and next month, when someone decides they need to add some other module, and has a precedent to follow. Then, suddenly we end up with 30 different modules included in our distribution, each one changed slightly from the CPAN one. Dual-lifed modules that live with perl5 are hard enough. -R
Re: [DOCS] Documentation tools
On 7 Feb 2004, at 00:53, Michael Scott wrote: On 6 Feb 2004, at 22:32, Leopold Toetsch wrote: - icu - lib/Test/* - lib/Pod/* are all standard thingys. I'm not thinking that we are gonna reinventing wheels nor that we are gonna copying existing wheels, so I'd vote for just removing all that from CVS. yep All non-trivial packages have some preliminaries. Some prominent notes in README and INSTALL can provide the necessary steps, how to get that source. I'd like to see Configure.pl say what's needed, and do what it can to help if requested. I'd like to remove non-modified, non-parrot Perl modules from lib and install them via CPAN.pm. I have a version here which works, but I remember from experience it can be tricky to set up CPAN.pm to work behind firewalls, so I'm wondering what collective wisdom has to say. Should we run CPAN.pm from Configure.pl or rely on prominent notes? Mike
Re: [DOCS] Documentation tools
At 3:40 PM +0100 3/4/04, Michael Scott wrote: On 7 Feb 2004, at 00:53, Michael Scott wrote: On 6 Feb 2004, at 22:32, Leopold Toetsch wrote: - icu - lib/Test/* - lib/Pod/* are all standard thingys. I'm not thinking that we are gonna reinventing wheels nor that we are gonna copying existing wheels, so I'd vote for just removing all that from CVS. yep All non-trivial packages have some preliminaries. Some prominent notes in README and INSTALL can provide the necessary steps, how to get that source. I'd like to see Configure.pl say what's needed, and do what it can to help if requested. I'd like to remove non-modified, non-parrot Perl modules from lib and install them via CPAN.pm. No. Sorry, definitely not. Parrot's config isn't going to install perl modules off the 'net any more than it's going to run apt-get on systems that support it. We either provide it or do without. -- Dan --it's like this--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: [DOCS] Documentation tools
On 4 Mar 2004, at 15:51, Dan Sugalski wrote: [...] I'd like to remove non-modified, non-parrot Perl modules from lib and install them via CPAN.pm. No. Sorry, definitely not. Parrot's config isn't going to install perl modules off the 'net any more than it's going to run apt-get on systems that support it. We either provide it or do without. Which is how I originally looked at it when I added Pod::Simple. But then Robert asked why are we including CPAN modules that we are not likely to change into the parrot repository?, and Leo suggested the prominent notes approach, which left me with the impression that this was something that had to be dealt with. So, do I just leave Pod::Simple there? Mike
Re: [DOCS] Documentation tools
On Mar 4, 2004, at 7:45 AM, Michael Scott wrote: On 4 Mar 2004, at 15:51, Dan Sugalski wrote: [...] I'd like to remove non-modified, non-parrot Perl modules from lib and install them via CPAN.pm. No. Sorry, definitely not. Parrot's config isn't going to install perl modules off the 'net any more than it's going to run apt-get on systems that support it. We either provide it or do without. Which is how I originally looked at it when I added Pod::Simple. But then Robert asked why are we including CPAN modules that we are not likely to change into the parrot repository?, and Leo suggested the prominent notes approach, which left me with the impression that this was something that had to be dealt with. So, do I just leave Pod::Simple there? Personally, I think it's worth a few KB for the convenience we currently have, of being able to grab the parrot source and build without additional installation. (All of lib is only 187 KB compressed, and that includes the Parrot:: modules.) JEff
Re: [DOCS] Documentation tools
I'd like to remove non-modified, non-parrot Perl modules from lib and install them via CPAN.pm. No. Sorry, definitely not. Parrot's config isn't going to install perl modules off the 'net any more than it's going to run apt-get on systems that support it. We either provide it or do without. Huh? Dan, what are you smoking? Every project has dependencies. For now, perl5 and a handful of modules are one of parrot's prereqs. That's quite reasonable. If someone can't install a few perl5 modules, they probably shouldn't be building parrot. There's no reason to include large, independently maintained modules like Pod::Simple in the parrot CVS tree and tarball. It just turns into a maintenance nightmare, should we ever start modifying these things. And while the parrot tree is relatively small right now - it won't always be. Might as well keep it small while we can. I don't understand why you are insisting on including these things. Please clarify. -R
Re: [DOCS] Documentation tools
On Thu, Mar 04, 2004 at 03:40:27PM +0100, Michael Scott wrote: : I'd like to remove non-modified, non-parrot Perl modules from lib and : install them via CPAN.pm. I have a version here which works, but I : remember from experience it can be tricky to set up CPAN.pm to work : behind firewalls, so I'm wondering what collective wisdom has to say. : Should we run CPAN.pm from Configure.pl or rely on prominent notes? The only sane course forward is to separate the notion of developer distribution from user distribution. The developer codebase should have no fat, and can have external dependencies out the wazoo. The user distribution (and there can be more than one--see Linux) provides all the bells and whistles that the distributor sees fit, and should generally shield the user from having to download anything commonly in use. Ideally, the developer codebase should be completely *unusable* by mere mortals, to prevent ISPs from installing that and claiming they support Perl. They need to be forced to install a user-oriented distribution. Just like you can't merely install the Linux kernel and say you're done. I think this is one of those situations where having our cake and eating it too is not just an option, but a requirement. Larry
Re: [DOCS] Documentation tools
Dan Sugalski [EMAIL PROTECTED] wrote: No. Sorry, definitely not. Parrot's config isn't going to install perl modules off the 'net any more than it's going to run apt-get on systems that support it. We either provide it or do without. What about ICU. There is already a new version pending (again). leo
Re: [DOCS] Documentation tools
No. Sorry, definitely not. Parrot's config isn't going to install perl modules off the 'net any more than it's going to run apt-get on systems that support it. We either provide it or do without. What about ICU. There is already a new version pending (again). Since we haven't actually used ICU yet, I see no reason to integrate the new version until we use the old one. And personally, I'd rather rip it out of the tree and say we're just going to link against the installed version -R
Re: [DOCS] Documentation tools
There's no reason to include large, independently maintained modules like Pod::Simple in the parrot CVS tree and tarball. It just turns into a maintenance nightmare, should we ever start modifying these things. [...] I don't understand why you are insisting on including these things. One reason might be reducing uncertainty. Including modules otherwise available from CPAN lets us control the versions used for parrot testing. We've already seen bugs resulting from using one version of perl rather than another. They are a pain to track down. Will myconfig start reporting on module version numbers too? Including modules insulates the parrot distribution from the vagaries of CPAN, and the enormously greater vagaries of peoples' local module installations. I can test parrot against any of my perl installs, without worrying about what is or isn't installed in them. I wonder how many potential testers we might lose if testing becomes an involved, site modifying exercise, rather than the current simple one? As you point out, these modules are not there to be edited. In a sense, they are there to prevent others from editing them, and thus affecting our users, without our being able to test them with the distribution first. Bundling modules when delivering software to a machine one doesn't control is actually quite common. Though admittedly something other languages (eg Tcl) have focused more on (and are better at;). The determinism seems perhaps worth the bloat. It's quite localize bloat after all. Mitchell (Though I certainly sympathize with the desire to scrub some of the accumulated cruft out the distribution... :)
Re: [DOCS] Documentation tools
The determinism seems perhaps worth the bloat. It's quite localize bloat after all. I disagree. We _want_ a heterogeneous environment -- a homogeneous environment doesn't exist in the real world -- most of your concerns were with tracking down the issues. Since we have parrotbug now (or real soon) we can take a better snapshot of whats going on. If we want to require certain versions, that becomes a problem ot some people. But we can do it by providing URL's to where people can download the specific versions and instructions on how to set that up for parrot's use only. But we don't need to bundle it _with_ Parrot. -R
Re: [DOCS] Documentation tools
At this point in the development cycle you can certainly make such arguments (although I would tend to fall on the side of consistency myself, at least for things that really Don't Matter in the grand scheme of things, such as POD modules). But once we start expecting people in the real world to compile this thing on their boxes in order to install perl, it would be extremely foolish to make them manually download and install perl6 + parrot + icu + perl5 + cpan modules 1 through 10, all from different sources. IMHO, the releases better include everything necessary to build the application, within reason. Consistency and simplicity counts for a lot. Why create headaches we don't need? The development environment can of course be more fluid. --Josh At 15:05 on 03/04/2004 PST, Robert Spier [EMAIL PROTECTED] wrote: The determinism seems perhaps worth the bloat. It's quite localize bloat after all. I disagree. We _want_ a heterogeneous environment -- a homogeneous environment doesn't exist in the real world -- most of your concerns were with tracking down the issues. Since we have parrotbug now (or real soon) we can take a better snapshot of whats going on. If we want to require certain versions, that becomes a problem ot some people. But we can do it by providing URL's to where people can download the specific versions and instructions on how to set that up for parrot's use only. But we don't need to bundle it _with_ Parrot. -R
Re: [DOCS] Documentation tools
But once we start expecting people in the real world to compile this thing on their boxes in order to install perl, it would be extremely foolish to make them manually download and install perl6 + parrot + icu + perl5 + cpan modules 1 through 10, all from different sources. Try building any other large system. We don't know what this is going to look like when perl6 is done. One thing we can always do is create a tarball of tarballs, or a web page that says: 1. click _here_ to download perl 5.12.1 2. click _here_ to download parrot 1.3 3. click _here_ to download perl 6.0.14 we've had enough trouble with ICU, keeping it up to date, and we're not even using it. (And I'd wager we never use it.) there are already existing, well known, methods for distributing all these things. Maybe I'm old school, but I'd rather download 5 small or medium sized things than one huge thing. It also makes it a lot easier to change/upgrade just one piece. Why are we reinventing wheels? Why are we shipping extra bits around? IMHO, the releases better include everything necessary to build the application, within reason. Consistency and simplicity counts for a lot. Why create headaches we don't need? within reason. Thats where we're way off right now. The development environment can of course be more fluid. Ok. So lets rip all the crap out, and in two years when it comes time to release 1.0, we can re-think what needs to go in. -R
Re: [DOCS] Documentation tools
Robert Spier [EMAIL PROTECTED] wrote: Pod::Simple is relatively easy to subclass. And Sean is pretty receptive to changes. [ more referenced source inside ] - icu - lib/Test/* - lib/Pod/* are all standard thingys. I'm not thinking that we are gonna reinventing wheels nor that we are gonna copying existing wheels, so I'd vote for just removing all that from CVS. All non-trivial packages have some preliminaries. Some prominent notes in README and INSTALL can provide the necessary steps, how to get that source. If we are going towards real user releases, we can provide complete packages including all, for now its just simpler to not ship (and maintain[1]) everything. *If* we need additions or changes to such prelim source code, please work out a simple scheme that works: $ man patch ... comes to my mind. I'd really like that have clarified towards next release at best. leo [1] IIRC there was already one icu update outside that finally got it into CVS - but the whole code is still unused.
Re: [DOCS] Documentation tools
On 6 Feb 2004, at 22:32, Leopold Toetsch wrote: - icu - lib/Test/* - lib/Pod/* are all standard thingys. I'm not thinking that we are gonna reinventing wheels nor that we are gonna copying existing wheels, so I'd vote for just removing all that from CVS. yep All non-trivial packages have some preliminaries. Some prominent notes in README and INSTALL can provide the necessary steps, how to get that source. I'd like to see Configure.pl say what's needed, and do what it can to help if requested. Meanwhile, I've been adding some perl code of my own which should give a more parroty feel to the docs. http://homepage.mac.com/michael_scott/Parrot/docs/html/index.html There are some links to actual files in the distribution (READMEs etc) which will be broken because it's not up there, but they work ok locally. As you can see the structure is lifted from the wiki, this is because it saved me thinking while I got it working. The Item, Group and Section modules in Parrot::Docs will make it fairly easy to set up alternative subsystem-based views of the content instead. Eagle eyes will note that I put the parrotcode.org css and small parrot png in docs/resources so that they work without a network. Hope I haven't transgressed again. Oh, btw, while googling for parrot and leap I found this (indirectly): http://news.bbc.co.uk/2/hi/science/nature/3430481.stm Mike
Re: [DOCS] Documentation tools
Suppose I could make a few changes to Pod-Simple, then our problem would be solved. But, being serious, say I'd decided to use Template-Toolkit, it would never have occurred to me to shove all of that in CVS. It always surprised me a that ICU was there, rather than just what was needed to get it to work. So, it seems just to be a question of adding a prerequisites phase to the config. I would propose that we leave Pod-Simple in CVS until I have time to implement that, then we can delete it (promise). Mike On 6 Feb 2004, at 01:39, Robert Spier wrote: I can possibly help it, so it's ok by me to delete lib/Pod, if that's the consensus. I'm not sure what the consensus is. But we should probably come to one. -R
Re: [DOCS] Documentation tools
Suppose I could make a few changes to Pod-Simple, then our problem would be solved. Pod::Simple is relatively easy to subclass. And Sean is pretty receptive to changes. never have occurred to me to shove all of that in CVS. It always surprised me a that ICU was there, rather than just what was needed to get it to work. I don't think ICU should be in there at all... but that's just my vote :) So, it seems just to be a question of adding a prerequisites phase to the config. I would propose that we leave Pod-Simple in CVS until I have time to implement that, then we can delete it (promise). I wasn't going to make any rash actions like deleting it on the CVS server side ;) It's there, there's no rush to get it out, but I think in general, we want to keep the parrot source from becoming immensely huge. -R
Re: [DOCS] Documentation tools
Ah, ok, my bad then. I'd just assumed that, apart from any need for modification, the other things were there simply to save having to tell everyone to go off and get them. I don't intend to change Pod-Simple if I can possibly help it, so it's ok by me to delete lib/Pod, if that's the consensus. Mike On 5 Feb 2004, at 06:31, Robert Spier wrote: I've added the Perl modules for the docs tools to lib/Parrot/IO and lib/Parrot/Docs. I've also added Pod-Simple (2.05) and Pod-Escapes (1.03) which they use. I probably blinked.. but why are we including CPAN modules that we are not likely to change into the parrot repository? -R
[DOCS] Documentation tools
I've added the Perl modules for the docs tools to lib/Parrot/IO and lib/Parrot/Docs. I've also added Pod-Simple (2.05) and Pod-Escapes (1.03) which they use. Running perl tools/docs/write_docs.pl should build the html tree in docs/html. I'd be interested to know of any problems encountered. On the updating front, I finished examples and did the other *.c file directories (chartypes, encodings, io, pf, types). Now I think I'll look at classes. Mike
