[DOCS] Documentation tools
Michael Scott
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
Robert Spier
> 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
Michael Scott
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
Robert Spier
> the consensus.
I'm not sure what the consensus is. But we should probably come to one.
-R
Michael Scott
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
Robert Spier
> 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
Leopold Toetsch
> 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.
Michael Scott
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
Michael Scott
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
Dan Sugalski
>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
d...@sidhe.org have teddy bears and even
teddy bears get drunk
Michael Scott
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
Jeff Clites
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
Leopold Toetsch
> 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
Robert Spier
> >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
Larry Wall
: I'd like to remove non-modified, non-parrot Perl modules from lib and
: 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
Robert Spier
> > 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
Mitchell N Charity
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... :)
Robert Spier
> 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
Josh Wilmes
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
Robert Spier
> 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
Jeff Clites
>> 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
Robert Spier
> > "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
Michael Scott
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.
Dan Sugalski
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 Sugalski
> > >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.
Ask Bjoern Hansen
[...]
> 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();