xmlxslt-devel

Re: Proposed PREAMBLE and POSTAMBLE

[<ma...@ev...>]

>>>>> "M" == Mike808  <mi...@ne...> writes:

    M> I've also added a CREDITS.pod file for project credits. Please
    M> update your own info. I'd like everyone to use their
    M> sourceforge email addresses in the code. Keeps spam out and it
    M> won't move around as you do.

I'd prefer to use my @everybody.org email as I own the domain and I'm
sure I'll keep it.  I'd bet that bron feels the same about his
@bron.net address.  As far as spam: I use RBL[1], so I don't really
run into that problem.

Mark

[1] http://mail-abuse.org/rbl/

-- 
The worst thing about new books is that they keep us from reading the old
ones. -Joseph Joubert (1754-1824)

Re: Proposed PREAMBLE and POSTAMBLE

[Mike808 <mi...@ne...>]

"Mark A. Hershberger" wrote:
> I'd prefer to use my @everybody.org email as I own the domain and I'm
> sure I'll keep it.

That's fine. As I said,
>    M> Please update your own info.

SF also runs theirs through RBL, and I knew everyone on the project
*has* a sourceforge address, so it was just a default.

Feel free to check out CREDITS.pod and update your info.

Bron can do the same.

Mike.

Merge of Bron's fork

[Mike808 <mi...@ne...>]

Bron - I've started your OO interface, but I think there will be a
performance hit for it. We can do some speedup to help a bit, though.

I didn't implement it though. I only got down to about line 1000 or so
in merging with your fork.

I don't know what you were doing (or trying to do) down in the guts
of some of the functions.

You should like the OO consistent style I've put everything in, and
I think you were attempting to do the same thing in your fork.

I also turned the big xsl-tag switch into a jump table, since all
of the tag methods have the same API. The code is cleaner and it
may even be faster (not real sure). I didn't want to freak anyone
out by using the magic goto (like AUTOLOADER does).

Mike.

Proposed PREAMBLE and POSTAMBLE

[Mike808 <mi...@ne...>]

Here's what I'm going to start using as a postamble. It was taken from
my lastest XLST.pm and I'm using it on the other files I'm working on.

I've split out the XML::DOM tag compression policy function into its
own package. This only happens at load time, so shouldn't be that big
an issue. Anybody doing XSLT on-the-fly with CGI deserves what they get.
It's in the XSLT folder and it's called "Tag_Compression.pm"

I've also added a CREDITS.pod file for project credits. Please update
your own info. I'd like everyone to use their sourceforge email 
addresses in the code. Keeps spam out and it won't move around as you
do.

Feel free to cut 'n paste into other files at will.
I'd leave all of the =head1 sections in. Just alter SEE ALSO, NOTES,
ACKNOWLEDGEMENTS, and AUTHORZ<>(S) as needed. The Z<> is needed due to
prevent pod2whatever from thinking it is a function and turning it into
a link to nowhere.

Mike.

- - - - Start PREAMBLE - - - - 
##############################################################################
#
# XML::XSLT
#
# This file is part of the XML::XSLT package.
#
# Copyright (C) 2000
# Geert Josten (gj...@sc...)
# Egon Willighagen (eg...@us...)
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
# See the file 'LICENSE' for details.
#
#(@) $Id: XSLT.pm,v 1.8.6.4 2000/07/13 21:09:11 hexmode Exp $
#
##############################################################################
- - - - END PREAMBLE - - - - 
	
- - - - Start POSTAMBLE - - - - 
##############################################################################

=head1 SEE ALSO

 XML::DOM

 The XSLT specification: http://www.w3.org/TR/xslt

=head1 NOTES

New releases will be announced on the perl-xml mailing list and to the 
XML::XSLT mailing list.

You can subscribe to the perl-xml list by sending a message to:

 sub...@ly...

You can subscribe to the XML::XSLT mailing list by sending a message to:

 xml...@li...

=head2 Bug Reports

Please post bug reports to

  http://sourceforge.net/bugs/?group_id=6054

=head1 ACKNOWLEDGEMENTS

=head1 AUTHORZ<>(S)

 Geert Josten (gj...@sc...)
 Egon Willighagen (eg...@us...)
 Bron Gondwana (br...@us...)
 Mark A. Hershberger (he...@us...)
 Michael King (mi...@us...)

=head1 COPYRIGHT

 Copyright (c) 2000
 Geert Josten (gj...@sc...)
 and
 Egon Willighagen (eg...@us...).
 All Rights Reserved.

=head1 LICENSE

When included as part of the XML::XSLT package, or as part of its
complete 
documentation whether printed or otherwise, this work may be distributed
only 
under the terms of Perl's Artistic License. Any distribution of this
file or 
derivatives thereof outside of or separate from this package require
that 
special arrangements be made with copyright holder.

See the file 'LICENSE' in this distribution for details of copy and 
distribution terms. It is a copy of the file 'Artistic' in the
distribution of 
Perl 5.002 or later.

=head1 AVAILABILITY

The latest version of this module is likely to be available from the
XML::XSLT
project web site:

 http://sourceforge.net/projects/xmlxslt/

The best place to discuss this code is via the project web site.

=head1 REVISION

 Revision: $Revision: 1.8.6.6 $
       On: $Date: 2000/07/13 21:09:11 $

=cut

Filename: $RCSfile: XSLT.pm,v $
Revision: $Revision: 1.8.6.5 $
   Label: $Name:  $

Last Chg: $Author: hexmode $ 
      On: $Date: 2000/07/13 21:09:11 $

  RCS ID: $Id: XSLT.pm,v 1.8.6.5 2000/07/13 21:09:11 hexmode Exp $
    Path: $Source: /cvsroot/xmlxslt/XML-XSLT/XSLT.pm,v $

Revision Log:
$Log: XSLConstant.pm,v $

- - - - END POSTAMBLE - - - -

Re: Direction

[<ma...@ev...>]

>>>>> "M" == Mike808  <mi...@ne...> writes:

    M> Heavily modifying the maint release,

[...]

    M> The indentation should be consistent, the style should look
    M> more organized, and the documentation tweaked.

All these are good points, but I have to ask: have you looked at my
0.30 pre-release or read the POD that comes with it?

I've done a small amount of documenting of the code there, but have
also done a substantial bit of work on the POD -- cleaning up the API,
documenting un-documented calls, etc.

This is stuff that should be merged because it has already been
announced.  I put the POD out for review and got at least Geert's ok.
I'd like to think that work isn't going to waste.

Also, note that committing changes that simply change the indention
will make the code un-mergeable.  If we are working to merge the
-maint branch with the main trunk, then it would be a good idea to
avoid the indention for now and wait till we get the branches merged
back in.

Mark.

-- 
The worst thing about new books is that they keep us from reading the old
ones. -Joseph Joubert (1754-1824)

Re: Authorship, Licensing, Copyright...

[Bron G. <br...@ne...>]

On Wed, Jul 19, 2000 at 01:55:20AM -0500, Mike808 wrote:
> Bron Gondwana wrote:
> > There's very much two schools of thought here - but once we start splitting
> > functionality into separate files, we'll need to either put all the docs
> > in one or do messy include stuff (I'm not sure how POD handles that)
> 
> I very much believe that each separate source file should stand alone.
> That means intact with embedded copyright/ownership/licensing/version
> info. That also means included POD. No module should be distributed 
> without POD. That doesn't mean that SomeModule.pm can't have a 
> SomeModule.pod to go along with it. Both should carry copyright 
> and licensing info within, the POD should have it both source-visible
> and perldoc visible.

I don't know what skipping POD/comments does to loadup times.. probably
not much, but where many files are grouped together as a set, I believe
a better solution is to say "this file is part of a set and belongs with
$OTHER_FILES, and may not be redistributed without $LICENCE and
$OTHER_FILES".  Requiring that the entire licence and changelog be in
modules that may be parsed many times a second seems rather silly to me.

>
> This is precisely to prevent 'out-of-context' issues due to our
> omission to exert these claims and rights. BTW, we are all in the
> good ole US of A, right? (Besides Geert and Egon, I know).

Damn, I knew I should be using my netizen.com.au addresses.  Um, that
would be a no.  Good old Oz-trailyer.

> Then if we need a cookbook or tutorial or overall POD doc, then we 
> just write something like a 'XSLT-cookbook.pm' or XSLT-tutorial.pm' 
> that only contains POD, so the 'disjoint docset' isn't an issue.

That's true, and probably a good point - but I don't think every file
has to stand alone.

> I'm not sure what you mean by 'messy include stuff'. I see nothing
> wrong with a 'SEE ALSO' section and a reference to the other PODs.
> This would be consistent with CORE Perl perldocs and pretty much all
> CPAN modules.

True, but something like a "supported functionality" section should be
in the main manpage, even though the functionality itself may be
documented in subpages.  CGI.pm is a bad case of excessive single-file
and large manpageness IMHO, but having many 2-3 page manpages is also
very annoying to those of us who like printing a copy of the manpage
and hilighter marking it if we're using the module a lot.

> On the licensing, I'm fine with Geert and Egon's (and mine)
> use of 'same terms as Perl itself' message.
> e.g.
> # This module is free software; you can redistribute it and/or
> # modify it under the same terms as Perl itself.

That seems fairly standard with Perl.

> As for copyright, well, technically, if I write it, I own the
> copyright unless I explicitly transfer it to someone/thing else.
> Hence a clear assignment of copyright to contributed work, like
> the Apache group does. I'll see if I can borrow some relevant
> text that isn't too lengthy and complicated.

If you're modifying someone else's original work, then it starts
getting messier, but yes - copyright is a messy issue.  If you
can summarise what the Apache group does, that would be fantastic.

> I've got some major changes to the 1.8.6.4 on the 
> cpan-0_2x-maint tree. I know there's a .5 I need to merge.
> 
> I found some missing '=' assignments buried in the code. Weird.
> Fixed. e.g. my $var some_function($a,$b,$c); # Missing '='???

The stuff I submitted during the 0.24 build was very messy..
courtesy of a slow link and my extreme tiredness at the time.

If you replace the code in there with the copy from 0.24 release
they missing ='s will all be fixed :)

> Also, I noticed some speedups with our hash accesses that we
> were wasting time doing copy-on-write operations. NOT Fixed.
> Noted with a comment.
> 
> Also, did some speedups by moving indirect references to lexicals.
> I'm about halfway through the code now.

Fantastic :)  I'll be throwing more work that way soon - but I have
spec writing to do for the rest of this week.  Grr..

-- 
Bron ( at least I seem to have a job and a passable salary )

Re: Authorship, Licensing, Copyright...

[Mike808 <mi...@ne...>]

Bron Gondwana wrote:
> There's very much two schools of thought here - but once we start splitting
> functionality into separate files, we'll need to either put all the docs
> in one or do messy include stuff (I'm not sure how POD handles that)

I very much believe that each separate source file should stand alone.
That means intact with embedded copyright/ownership/licensing/version
info. That also means included POD. No module should be distributed 
without POD. That doesn't mean that SomeModule.pm can't have a 
SomeModule.pod to go along with it. Both should carry copyright 
and licensing info within, the POD should have it both source-visible
and perldoc visible.

This is precisely to prevent 'out-of-context' issues due to our
omission to exert these claims and rights. BTW, we are all in the 
good ole US of A, right? (Besides Geert and Egon, I know).

Then if we need a cookbook or tutorial or overall POD doc, then we 
just write something like a 'XSLT-cookbook.pm' or XSLT-tutorial.pm' 
that only contains POD, so the 'disjoint docset' isn't an issue.

I'm not sure what you mean by 'messy include stuff'. I see nothing
wrong with a 'SEE ALSO' section and a reference to the other PODs.
This would be consistent with CORE Perl perldocs and pretty much all
CPAN modules.

On the licensing, I'm fine with Geert and Egon's (and mine)
use of 'same terms as Perl itself' message.
e.g.
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.


As for copyright, well, technically, if I write it, I own the
copyright unless I explicitly transfer it to someone/thing else.
Hence a clear assignment of copyright to contributed work, like
the Apache group does. I'll see if I can borrow some relevant
text that isn't too lengthy and complicated.

I've got some major changes to the 1.8.6.4 on the 
cpan-0_2x-maint tree. I know there's a .5 I need to merge.

I found some missing '=' assignments buried in the code. Weird.
Fixed. e.g. my $var some_function($a,$b,$c); # Missing '='???

Also, I noticed some speedups with our hash accesses that we
were wasting time doing copy-on-write operations. NOT Fixed.
Noted with a comment.

Also, did some speedups by moving indirect references to lexicals.
I'm about halfway through the code now.

Mike.

Re: Authorship, Licensing, Copyright...

[Bron G. <br...@ne...>]

On Tue, Jul 18, 2000 at 11:50:15PM -0500, Mike808 wrote:
> How do we deal with new modules as code 'breaks up' from the original
> XSLT.pm in terms of authorship and copyright holders?

I think an "all authors who've contributed" list over the entire thing.

Separate files and perl modules doesn't mean separate "product" level 
stuff.

> I am assuming that we are unanimous in licensing under the Perl Artistic
> License?

Artistic/GPL combination seems to be the most common, though possibly
LGPL depending on feeling here.  It needs to be usable without having to
open entire applications from the market-share point of view.  I just
received an newsletter from Developer.com saying that Microsoft is
pushing itself as the XML/Unicode platform, and I place competing with
this above GPL purity on my priority list.

> I'll look into if there's a precedent for transferring our copyrights
> to the 'SourceForge XML::XSLT Project Team' in a mode similar to the
> Apache copyrights and licensing. Or to Geert and Egon? Or to each
> his own? Is tab conversion a 'copyrightable' activity? Crap. I just
> knew it that Shakespeare was right ... my head hurts...
> 
> We should lay out our guidelines for required notices amongst ourselves
> and enforce it for all files before we have to retro-fit too much.
> I'm not saying it has to be complicated, just consistent and start
> doing this sooner rather than later.

Yep, certainly.. on the -devel list probably.

> So far, the leading '#' pre-amble seems OK, but I'd like to put
> the proper attribution to the team now that it's mangled pretty good
> by all of us. I *really* think we need the CVS keyword post-amble
> (minus the LOG keyword - I agree with Mark) and all POD going
> after the __END__ statement. I also like the =begin internal_doc
> or =begin ignore type of POD notation for lopping off big chunks of 
> code or internal documentation without having to prefix each line
> with a '#'. Just my twopence.

There's very much two schools of thought here - but once we start splitting
functionality into separate files, we'll need to either put all the docs
in one or do messy include stuff (I'm not sure how POD handles that)

-- 
Bron ( learning Docbook atm, whee )

Authorship, Licensing, Copyright...

[Mike808 <mi...@ne...>]

Well, now that we're a team and it's not just Geert and Egon anymore,
we should decide how we want to do this.

Any examples from other SourceForge teams?

How do we deal with new modules as code 'breaks up' from the original
XSLT.pm in terms of authorship and copyright holders?

I am assuming that we are unanimous in licensing under the Perl Artistic
License?

I'll look into if there's a precedent for transferring our copyrights
to the 'SourceForge XML::XSLT Project Team' in a mode similar to the
Apache copyrights and licensing. Or to Geert and Egon? Or to each
his own? Is tab conversion a 'copyrightable' activity? Crap. I just
knew it that Shakespeare was right ... my head hurts...

We should lay out our guidelines for required notices amongst ourselves
and enforce it for all files before we have to retro-fit too much.
I'm not saying it has to be complicated, just consistent and start
doing this sooner rather than later.

So far, the leading '#' pre-amble seems OK, but I'd like to put
the proper attribution to the team now that it's mangled pretty good
by all of us. I *really* think we need the CVS keyword post-amble
(minus the LOG keyword - I agree with Mark) and all POD going
after the __END__ statement. I also like the =begin internal_doc
or =begin ignore type of POD notation for lopping off big chunks of 
code or internal documentation without having to prefix each line
with a '#'. Just my twopence.

Mike.

Re: cvs

[Mike808 <mi...@ne...>]

Bron Gondwana wrote:
> > I really like Bron's idea about moving these `underbar' functions to a
> > seperate auxilliary sub-package.  That gives a clean interface to the
> > XML::XSLT library and makes it clear(er) that those functions are not
> > part of our public API.

I'm moving the tag_compression thingy out altogether so it becomes
a simple 'use XML::XSLT::Tag_Compression;' in the main module. The
docs go with it and we can have lexical file-scoped variables.

> Splitting the code into sections and separate files is good.  As is an
> internal API structure - for example I think all of value-of, apply-templates,
> etc should be in a single file which has a name something like
> XML::XSLT::BaseActions (maybe that's not the best name though)

Gee, this is starting to look more like the 'other XML::XSLT' ... :)

> > Shall we merge BRON1 into the developement branch?
> 
> Possibly.  Remember that there's some seriously broken changes that I made in
> places not realy understanding what I'd done - and I haven't had time to check
> it over again.  Specifically, I'm quite sure I broke variables.

> > I'll get rid of URI::Heuristic and LWP::Simple in my code
What do you need them for? I'm thinking you were looking for a way
to sniff a filename to see if it is a reachable URL? If so, I've
some some extensive work on that implementing URI-fetching from
porting the Java. It's builtin to Java, but not Perl. :(
And Java has this nifty InvalidURLException, so I had to fake one
with LWP. It's not pretty, but it does work.

I'll see what I can do when I take a look at what Bron's done.

> > Mark.  (Also sending to -devel, but it looks like neither you nor Bron
> > are on the list.)

Am now.

Heavily modifying the maint release, and I'll have to merge in the
typo fix that came in after. The indentation should be consistent,
the style should look more organized, and the documentation tweaked.

Mike.

Re: cvs

[Bron G. <br...@ne...>]

On Tue, Jul 18, 2000 at 04:20:00AM -0500, Mark A. Hershberger wrote:
> >>>>> "M" == Mike808  <mi...@ne...> writes:
> 
>     M> On an unrelated front, we've got double-underbar methods and
>     M> underbar methods and I'm not sure of Geert's intent via naming
>     M> conventions. Perhaps he can help with a short note and we can
>     M> document it. That way, we can remain consistent.
> 
> I really like Bron's idea about moving these `underbar' functions to a
> seperate auxilliary sub-package.  That gives a clean interface to the
> XML::XSLT library and makes it clear(er) that those functions are not
> part of our public API.

Splitting the code into sections and separate files is good.  As is an
internal API structure - for example I think all of value-of, apply-templates,
etc should be in a single file which has a name something like 
XML::XSLT::BaseActions (maybe that's not the best name though)

> Shall we merge BRON1 into the developement branch?

Possibly.  Remember that there's some seriously broken changes that I made in
places not realy understanding what I'd done - and I haven't had time to check
it over again.  Specifically, I'm quite sure I broke variables.

>     M> If we're not too worried, why the compelling need to switch
>     M> from hashes to arrays?
> 
> Lack of self-control ;->  ?
> 
> I was implementing the newer API that I had talked about and that
> other people seemed to want.  I started playing around with the
> arraryref implementation and it stuck.
> 
> You are right that the hashref is more "mergable", though.

Hashref is more maintainable, which is a good thing.  It's also more
back-compatible.

>     M> Well, I can focus on _add_node and _evaluate_element for
>     M> starters.  BEGIN's a pig, but it's a one-time deal, so I'm not
>     M> that worried.
> 
> I'll get rid of URI::Heuristic and LWP::Simple in my code -- things
> that slow it down substantially.  I'll also go back to the hashref
> implementation (which is really just a search and replace away) and
> work on making it more "mergable" with your work on the maint branch.
> 

They may be worth eval()ing in iff needed.  Something like:

if ($filename =~ m!^http://! or $filename =~ m!^ftp://!) {
    eval q{
        require LWP::Simple;
        LWP::Simple::import();
        require URI::Heuristic;
        URI::Heuristic::import();
    };
}

> Finally, I thought that I had committed your work on the -maint
> branch, but it appears that I haven't.  Could you re-commit it?
> 
> Mark.  (Also sending to -devel, but it looks like neither you nor Bron
> are on the list.)

Oops, I knew there was something I missed.  I've signed up per...@br...
to both of them now, and I'll remove whatever the other address was once I
get duplicate messages.

-- 
Bron ( back at work :)

Re: cvs

[<ma...@ev...>]

>>>>> "M" == Mike808  <mi...@ne...> writes:

    M> Maybe some discussion of what we're trying to do with our
    M> changes can help keep things more 'merge-able'.

Agreed... more below.

    M> On an unrelated front, we've got double-underbar methods and
    M> underbar methods and I'm not sure of Geert's intent via naming
    M> conventions. Perhaps he can help with a short note and we can
    M> document it. That way, we can remain consistent.

I really like Bron's idea about moving these `underbar' functions to a
seperate auxilliary sub-package.  That gives a clean interface to the
XML::XSLT library and makes it clear(er) that those functions are not
part of our public API.

Shall we merge BRON1 into the developement branch?

    M> If we're not too worried, why the compelling need to switch
    M> from hashes to arrays?

Lack of self-control ;->  ?

I was implementing the newer API that I had talked about and that
other people seemed to want.  I started playing around with the
arraryref implementation and it stuck.

You are right that the hashref is more "mergable", though.

    M> Well, I can focus on _add_node and _evaluate_element for
    M> starters.  BEGIN's a pig, but it's a one-time deal, so I'm not
    M> that worried.

I'll get rid of URI::Heuristic and LWP::Simple in my code -- things
that slow it down substantially.  I'll also go back to the hashref
implementation (which is really just a search and replace away) and
work on making it more "mergable" with your work on the maint branch.

Finally, I thought that I had committed your work on the -maint
branch, but it appears that I haven't.  Could you re-commit it?

Mark.  (Also sending to -devel, but it looks like neither you nor Bron
are on the list.)