[32711] in Perl-Users-Digest
Perl-Users Digest, Issue: 3975 Volume: 11
daemon@ATHENA.MIT.EDU (Perl-Users Digest)
Thu Jun 27 11:09:18 2013
Date: Thu, 27 Jun 2013 08:09:04 -0700 (PDT)
From: Perl-Users Digest <Perl-Users-Request@ruby.OCE.ORST.EDU>
To: Perl-Users@ruby.OCE.ORST.EDU (Perl-Users Digest)
Perl-Users Digest Thu, 27 Jun 2013 Volume: 11 Number: 3975
Today's topics:
Re: CPAN vs. POD outside of .pm (.pl) files? <ben@morrow.me.uk>
issues with POD <oneingray@gmail.com>
Re: issues with POD <ben@morrow.me.uk>
Re: issues with POD <oneingray@gmail.com>
Re: issues with POD <ben@morrow.me.uk>
Re: Tree::Range 0.1 released <oneingray@gmail.com>
Re: Tree::Range 0.1 released <ben@morrow.me.uk>
Re: Tree::Range 0.1 released <oneingray@gmail.com>
Re: Tree::Range 0.1 released <ben@morrow.me.uk>
Re: Tree::Range 0.1 released <oneingray@gmail.com>
Digest Administrivia (Last modified: 6 Apr 01) (Perl-Users-Digest Admin)
----------------------------------------------------------------------
Date: Thu, 27 Jun 2013 08:12:00 +0100
From: Ben Morrow <ben@morrow.me.uk>
Subject: Re: CPAN vs. POD outside of .pm (.pl) files?
Message-Id: <075t9a-b882.ln1@anubis.morrow.me.uk>
Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> Ben Morrow <ben@morrow.me.uk> writes:
> >>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>
> >> ACK, thanks! Hopefully, such indexing won't insist on the use of a
> >> HYPHEN-MINUS (U+002D) there, instead of the arguably more
> >> appropriate EN DASH (U+2013).
>
> > I wouldn't muck about with the formatting of the NAME section.
>
> FWIW, http://search.cpan.org/ seems to handle it just fine.
> Consider, e. g.:
>
> http://search.cpan.org/perldoc?Tree::Range::base
> http://search.cpan.org/perldoc?Tree::Range::RB
>
> Preasumably, it just indexes the PODs by the filename.
Presumably.
> > pod2man in particular is quite picky about it, and there are other
> > tools which rely on the format being right.
>
> As it seems, ExtUtils::MakeMaker assumes (SPACE, HYPHEN-MINUS,
> SPACE) for the delimiter while handling ABSTRACT_FROM, and I'm
> considering it a bug (yet to be filed.)
It's not a bug. It's part of the syntax of a properly-formatted perldoc.
Pod::Checker looks for a hyphen as well.
As I said, don't muck about with the formatting, there's no point. Note
that Pod::Man (at least) converts that hyphen into the roff escape
sequence for an endash (along with other instances of " - "), so if you
don't get endashes in the output it's because your formatter doesn't
know how to produce them. 'groff -man -Tps' at least will get them
right.
> I've not seen any problem with pod2man(1) vs. NAME as of yet.
> What should I take note of?
>
> (It appears to assume that --quotes= is a string of two
> /octets/, not two /characters,/ though.)
Since the roff emitted by pod2man is normally ASCII-only, what's the
difference?
Ben
------------------------------
Date: Thu, 27 Jun 2013 08:50:12 +0000
From: Ivan Shmakov <oneingray@gmail.com>
Subject: issues with POD
Message-Id: <87li5w7xa3.fsf_-_@violet.siamics.net>
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
[...]
>>> pod2man in particular is quite picky about it, and there are other
>>> tools which rely on the format being right.
>> As it seems, ExtUtils::MakeMaker assumes (SPACE, HYPHEN-MINUS,
>> SPACE) for the delimiter while handling ABSTRACT_FROM, and I'm
>> considering it a bug (yet to be filed.)
> It's not a bug. It's part of the syntax of a properly-formatted
> perldoc.
Which I see no reason /not/ to extend.
> Pod::Checker looks for a hyphen as well.
> As I said, don't muck about with the formatting, there's no point.
> Note that Pod::Man (at least) converts that hyphen into the roff
> escape sequence for an endash (along with other instances of " - "),
Frankly, I consider the unconditional replacement of " - " to be
a hack by itself.
Why, I've seen a Usenet poster who'd use groff to format his
messages. Guess what he'd end up when quoting code?
> so if you don't get endashes in the output it's because your
> formatter doesn't know how to produce them.
Apparently, the HTML formatter at http://search.cpan.org/
doesn't know how to produce EN DASHes, either.
--cut: http://search.cpan.org/perldoc?Digest --
NAME ^-
Digest - Modules that calculate message digests
--cut: http://search.cpan.org/perldoc?Digest --
Note the HYPHEN-MINUS propagated to the resulting HTML.
... Indeed, my first thought was to use DocBook or XHTML for the
documentation right from the start, so to completely avoid all
those 40 years of formatting mess. Somehow, however, I became
assured that persuading http://search.cpan.org/ to allow for
XHTML documentation would be next to impossible a task, which is
why I've ended up following the mainstream.
Not that I'm particularly happy with it.
(A reminder to myself: suggest updates to [1].)
[1] http://www.tldp.org/HOWTO/DocBook-Demystification-HOWTO/
> 'groff -man -Tps' at least will get them right.
Please note that -Tps produces not a document, but a program to
be executed (by a PostScript interpreter, in this case), which
has implications to both security and software freedom.
(Not unlike HTML "adorned" with JavaScript, Java, or
Adobe Flash, which became such a commonplace on the Web.)
Therefore, unless there's a very good reason to use PostScript,
my suggestion would be to always stick to PDF. (Or perhaps SVG,
as long as single-page vector graphics is concerned.)
>> I've not seen any problem with pod2man(1) vs. NAME as of yet. What
>> should I take note of?
>> (It appears to assume that --quotes= is a string of two /octets/,
>> not two /characters,/ though.)
> Since the roff emitted by pod2man is normally ASCII-only, what's the
> difference?
First of all, pod2man(1) supports --utf8. Then, even if
ASCII-only roff code is requested, pod2man(1) should try to
convert the --quotes= characters to the appropriate roff
escapes, just as it's claimed it does for non-ASCII sources:
[...] Many *roff implementations cannot handle non-ASCII
characters, so this means all non-ASCII characters are converted
either to a *roff escape sequence that tries to create a properly
accented character (at least for troff output) or to "X".
--
FSF associate member #7257
------------------------------
Date: Thu, 27 Jun 2013 12:32:16 +0100
From: Ben Morrow <ben@morrow.me.uk>
Subject: Re: issues with POD
Message-Id: <0fkt9a-kmb2.ln1@anubis.morrow.me.uk>
Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> Ben Morrow <ben@morrow.me.uk> writes:
> >>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>
> >> As it seems, ExtUtils::MakeMaker assumes (SPACE, HYPHEN-MINUS,
> >> SPACE) for the delimiter while handling ABSTRACT_FROM, and I'm
> >> considering it a bug (yet to be filed.)
>
> > It's not a bug. It's part of the syntax of a properly-formatted
> > perldoc.
>
> Which I see no reason /not/ to extend.
'I see no reason not to extend the syntax of HTML to allow Unicode
quotes as well as ASCII. They're *so* much prettier.' (cf. xthread.)
> > Pod::Checker looks for a hyphen as well.
>
> > As I said, don't muck about with the formatting, there's no point.
> > Note that Pod::Man (at least) converts that hyphen into the roff
> > escape sequence for an endash (along with other instances of " - "),
>
> Frankly, I consider the unconditional replacement of " - " to be
> a hack by itself.
Pod is, by design, a somewhat loosely-specified format, mostly or
(originally) entirely in ASCII, which relies on the formatter to make
things look pretty where that's necessary. The format has been tightened
up a little recently (it's no longer considered appropriate for the
formatter to turn random references like 'printf(3)' into L<>, for
instance), but this sort of intuition about punctuation is entirely
expected. Inconsistency is also, necessarily, expected.
> > so if you don't get endashes in the output it's because your
> > formatter doesn't know how to produce them.
>
> Apparently, the HTML formatter at http://search.cpan.org/
> doesn't know how to produce EN DASHes, either.
Apparently not. Apparently whoever wrote the relevant bit of code didn't
think it was terribly important.
> ... Indeed, my first thought was to use DocBook or XHTML
Ewww, yuck. Formats designed by and for pedants.
> for the
> documentation right from the start, so to completely avoid all
> those 40 years of formatting mess. Somehow, however, I became
> assured that persuading http://search.cpan.org/ to allow for
> XHTML documentation would be next to impossible a task, which is
> why I've ended up following the mainstream.
>
> Not that I'm particularly happy with it.
Heh. I can just picture the conversation... Not to mention that
command-line perldoc would no longer function, making your modules
unusable.
> > 'groff -man -Tps' at least will get them right.
>
> Please note that -Tps produces not a document, but a program to
> be executed (by a PostScript interpreter, in this case), which
> has implications to both security
That is a relevant concern under some circumstances; this is not one of
them. (I have, somewhat reluctantly, moved to using PDF instead of
PostScript almost exclusively. I like PostScript: it's comfortingly
insane. (The same could be said about Perl.))
> and software freedom.
Don't be so ridiculous.
> Therefore, unless there's a very good reason to use PostScript,
> my suggestion would be to always stick to PDF. (Or perhaps SVG,
> as long as single-page vector graphics is concerned.)
In this particular case I had a rather good reason: my version of groff
doesn't have a -Tpdf device.
> >> I've not seen any problem with pod2man(1) vs. NAME as of yet. What
> >> should I take note of?
>
> >> (It appears to assume that --quotes= is a string of two /octets/,
> >> not two /characters,/ though.)
>
> > Since the roff emitted by pod2man is normally ASCII-only, what's the
> > difference?
>
> First of all, pod2man(1) supports --utf8.
That's new(ish), and not particularly well-supported.
> Then, even if
> ASCII-only roff code is requested, pod2man(1) should try to
> convert the --quotes= characters to the appropriate roff
> escapes, just as it's claimed it does for non-ASCII sources:
The characters passed to --quotes aren't the characters as they will
appear in the output, they are roff escapes. (I don't really understand
roff, but the characters you pass are inserted directly into a .ds
line.) Remember, all this stuff comes from perl 5.000, before perl (or
groff, I expect) had any sort of Unicode support.
Ben
------------------------------
Date: Thu, 27 Jun 2013 12:48:53 +0000
From: Ivan Shmakov <oneingray@gmail.com>
Subject: Re: issues with POD
Message-Id: <8761wz90sq.fsf@violet.siamics.net>
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>> As it seems, ExtUtils::MakeMaker assumes (SPACE, HYPHEN-MINUS,
>>>> SPACE) for the delimiter while handling ABSTRACT_FROM, and I'm
>>>> considering it a bug (yet to be filed.)
>>> It's not a bug. It's part of the syntax of a properly-formatted
>>> perldoc.
>> Which I see no reason /not/ to extend.
> 'I see no reason not to extend the syntax of HTML to allow Unicode
> quotes as well as ASCII. They're *so* much prettier.' (cf. xthread.)
The HTML syntax /allows/ Unicode quotes. Inside the payload,
that is. (Which the text of the NAME section certainly is.)
The good thing about HTML is that it doesn't try to parse
anything outside of (roughly) the <tags /> and &entities;.
Ever.
[...]
>> Frankly, I consider the unconditional replacement of " - " to be a
>> hack by itself.
> Pod is, by design, a somewhat loosely-specified format, mostly or
> (originally) entirely in ASCII, which relies on the formatter to make
> things look pretty where that's necessary. The format has been
> tightened up a little recently (it's no longer considered appropriate
> for the formatter to turn random references like 'printf(3)' into
> L<>, for instance), but this sort of intuition about punctuation is
> entirely expected. Inconsistency is also, necessarily, expected.
... And so is unpredictability.
>>> so if you don't get endashes in the output it's because your
>>> formatter doesn't know how to produce them.
>> Apparently, the HTML formatter at http://search.cpan.org/ doesn't
>> know how to produce EN DASHes, either.
> Apparently not. Apparently whoever wrote the relevant bit of code
> didn't think it was terribly important.
But I do. So, assuming that my intent is to provide quality
documentation (both the contents and the form) for the users of
the software I develop, should I satisfy the NAME convention, at
the cost of having to host the /proper/ HTML renditions of the
documentation by myself? Or should I instead disregard the
convention -- used by the developer's tools I won't use myself
anyway, -- to ensure that certain well-known Web resource will
have the documentation rendered properly?
>> ... Indeed, my first thought was to use DocBook or XHTML
> Ewww, yuck. Formats designed by and for pedants.
... Remind me not to ask you about TEI, then...
>> for the documentation right from the start, so to completely avoid
>> all those 40 years of formatting mess. Somehow, however, I became
>> assured that persuading http://search.cpan.org/ to allow for XHTML
>> documentation would be next to impossible a task, which is why I've
>> ended up following the mainstream.
>> Not that I'm particularly happy with it.
> Heh. I can just picture the conversation... Not to mention that
> command-line perldoc would no longer function, making your modules
> unusable.
"Command-line perldoc"? What's it?
>>> 'groff -man -Tps' at least will get them right.
>> Please note that -Tps produces not a document, but a program to be
>> executed (by a PostScript interpreter, in this case), which has
>> implications to both security
> That is a relevant concern under some circumstances; this is not one
> of them.
It's a valid concern whenever the code comes from a generally
untrusted source. Such as from a Web site its author put it to.
(Which is how the documentation for free software packages is
often distributed.)
> (I have, somewhat reluctantly, moved to using PDF instead of
> PostScript almost exclusively. I like PostScript: it's comfortingly
> insane. (The same could be said about Perl.))
Still, I don't quite understand why one might want to use an
ad-hoc graphics language, when there're general-purpose ones,
with a number of graphics libraries to choose from? (And that
includes Perl, BTW.)
Pretty much the same applies to the ad-hoc formatter languages,
such as roff or TeX. Or to the usual hacks, like having the
"document conversion" chain run as follows:
document.foo -> (conversion) -> program -> (interpreter) -> document.bar
>> and software freedom.
> Don't be so ridiculous.
Well, looking at the license the software I use to produce
PostScript may attach to the pieces of the code which end up in
the resulting "document" isn't exactly the thing I'd like to
spend my time on.
The same applies to the license for the JavaScript code the Web
sites I visit employ. Which is one more reason to prefer Lynx.
>> Therefore, unless there's a very good reason to use PostScript, my
>> suggestion would be to always stick to PDF. (Or perhaps SVG, as
>> long as single-page vector graphics is concerned.)
> In this particular case I had a rather good reason: my version of
> groff doesn't have a -Tpdf device.
To me, it looks much more like a very good reason to update the
particular groff install.
[...]
>>>> (It appears to assume that --quotes= is a string of two /octets/,
>>>> not two /characters,/ though.)
>>> Since the roff emitted by pod2man is normally ASCII-only, what's
>>> the difference?
>> First of all, pod2man(1) supports --utf8.
> That's new(ish), and not particularly well-supported.
The more's the effort, the better's the support. And
identifying (and reporting) bugs is part of such an effort.
(Unless the agreement would be to just drop POD altogether, and
move on to the better tools. Which I still hope for, even
understanding all the improbability of such a decision.)
>> Then, even if ASCII-only roff code is requested, pod2man(1) should
>> try to convert the --quotes= characters to the appropriate roff
>> escapes, just as it's claimed it does for non-ASCII sources:
> The characters passed to --quotes aren't the characters as they will
> appear in the output, they are roff escapes. (I don't really
> understand roff, but the characters you pass are inserted directly
> into a .ds line.)
Which means that it may require a more thorough code change to
fix the issue. (Thanks for the pointer, BTW.)
> Remember, all this stuff comes from perl 5.000, before perl (or
> groff, I expect) had any sort of Unicode support.
How could this justify having the bug remain unfixed?
--
FSF associate member #7257
------------------------------
Date: Thu, 27 Jun 2013 14:53:41 +0100
From: Ben Morrow <ben@morrow.me.uk>
Subject: Re: issues with POD
Message-Id: <5ost9a-4fc2.ln1@anubis.morrow.me.uk>
Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> Ben Morrow <ben@morrow.me.uk> writes:
> >>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> Ben Morrow <ben@morrow.me.uk> writes:
> >>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>
> >>>> As it seems, ExtUtils::MakeMaker assumes (SPACE, HYPHEN-MINUS,
> >>>> SPACE) for the delimiter while handling ABSTRACT_FROM, and I'm
> >>>> considering it a bug (yet to be filed.)
>
> >>> It's not a bug. It's part of the syntax of a properly-formatted
> >>> perldoc.
>
> >> Which I see no reason /not/ to extend.
>
> > 'I see no reason not to extend the syntax of HTML to allow Unicode
> > quotes as well as ASCII. They're *so* much prettier.' (cf. xthread.)
>
> The HTML syntax /allows/ Unicode quotes. Inside the payload,
> that is. (Which the text of the NAME section certainly is.)
No, it isn't. That's exactly my point. The content of the NAME section
is syntax, and it needs to look like
<title> - <abstract>
with an ASCII hyphen. You may not like this, but that's the way it is.
> >>> so if you don't get endashes in the output it's because your
> >>> formatter doesn't know how to produce them.
>
> >> Apparently, the HTML formatter at http://search.cpan.org/ doesn't
> >> know how to produce EN DASHes, either.
>
> > Apparently not. Apparently whoever wrote the relevant bit of code
> > didn't think it was terribly important.
>
> But I do. So, assuming that my intent is to provide quality
> documentation (both the contents and the form) for the users of
> the software I develop, should I satisfy the NAME convention, at
> the cost of having to host the /proper/ HTML renditions of the
> documentation by myself? Or should I instead disregard the
> convention -- used by the developer's tools I won't use myself
> anyway, -- to ensure that certain well-known Web resource will
> have the documentation rendered properly?
The former. The assumption about NAME formatting is widespread, and you
don't know what types of systems people might be using your module on or
what sort of Pod-formatting tools they might have. Portability is more
important than typographical niceties.
> >> for the documentation right from the start, so to completely avoid
> >> all those 40 years of formatting mess. Somehow, however, I became
> >> assured that persuading http://search.cpan.org/ to allow for XHTML
> >> documentation would be next to impossible a task, which is why I've
> >> ended up following the mainstream.
>
> >> Not that I'm particularly happy with it.
>
> > Heh. I can just picture the conversation... Not to mention that
> > command-line perldoc would no longer function, making your modules
> > unusable.
>
> "Command-line perldoc"? What's it?
Are you serious? Run 'perldoc Pod::Man' from your shell prompt.
More generally, providing HTML documentation means you *only* provide
HTML documentation. Pod can be converted to a great many formats (that's
the point).
> >>> 'groff -man -Tps' at least will get them right.
>
> >> Please note that -Tps produces not a document, but a program to be
> >> executed (by a PostScript interpreter, in this case), which has
> >> implications to both security
>
> > That is a relevant concern under some circumstances; this is not one
> > of them.
>
> It's a valid concern whenever the code comes from a generally
> untrusted source. Such as from a Web site its author put it to.
> (Which is how the documentation for free software packages is
> often distributed.)
Perl documentation distributed in any format other than Pod is
worthless, since perldoc can't find it.
> > (I have, somewhat reluctantly, moved to using PDF instead of
> > PostScript almost exclusively. I like PostScript: it's comfortingly
> > insane. (The same could be said about Perl.))
>
> Still, I don't quite understand why one might want to use an
> ad-hoc graphics language, when there're general-purpose ones,
> with a number of graphics libraries to choose from? (And that
> includes Perl, BTW.)
Because my printer speaks PostScript? (Actually it doesn't, but
historically that was the reason for using it.)
> >> and software freedom.
>
> > Don't be so ridiculous.
>
> Well, looking at the license the software I use to produce
> PostScript may attach to the pieces of the code which end up in
> the resulting "document" isn't exactly the thing I'd like to
> spend my time on.
Me either. What makes you think the Turing-completeness of the language
used makes any difference to that, though? I very much doubt any such
licences are enforcable, in any case; certainly not if you're just using
the document as a document, and not trying to pick it apart and use the
bits to write your own PostScript driver.
> >> Therefore, unless there's a very good reason to use PostScript, my
> >> suggestion would be to always stick to PDF. (Or perhaps SVG, as
> >> long as single-page vector graphics is concerned.)
>
> > In this particular case I had a rather good reason: my version of
> > groff doesn't have a -Tpdf device.
>
> To me, it looks much more like a very good reason to update the
> particular groff install.
That would be the FreeBSD base system. The groff there is not going to
be updated, it's going to be replaced, because newer groffs are GPLv3.
> (Unless the agreement would be to just drop POD altogether, and
> move on to the better tools. Which I still hope for, even
> understanding all the improbability of such a decision.)
We're not going to do that. We *like* Pod. Personally, when I'm writing
technical documentation, I would write in Pod for choice. I appreciate
its lack of clutter.
> >> Then, even if ASCII-only roff code is requested, pod2man(1) should
> >> try to convert the --quotes= characters to the appropriate roff
> >> escapes, just as it's claimed it does for non-ASCII sources:
>
> > The characters passed to --quotes aren't the characters as they will
> > appear in the output, they are roff escapes. (I don't really
> > understand roff, but the characters you pass are inserted directly
> > into a .ds line.)
>
> Which means that it may require a more thorough code change to
> fix the issue. (Thanks for the pointer, BTW.)
...no, it means that changing it would break backcompat, so it's
probably not going to happen. (Not to mention that the whole question of
dealing with non-ASCII command-line arguments is largely unsolved on
non-Win32 systems.)
> > Remember, all this stuff comes from perl 5.000, before perl (or
> > groff, I expect) had any sort of Unicode support.
>
> How could this justify having the bug remain unfixed?
Because noone in a position to change it thinks it's a bug, or thinks
it's worth fixing? We're talking about pod2man here; I doubt anyone's
run it with --quotes for a very long time.
Ben
------------------------------
Date: Thu, 27 Jun 2013 08:12:08 +0000
From: Ivan Shmakov <oneingray@gmail.com>
Subject: Re: Tree::Range 0.1 released
Message-Id: <87ppv87z1j.fsf@violet.siamics.net>
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>> So, I've ended up with Tree::Range::RB, and Tree::Range::base for
>> the ->get_range () and ->range_set () methods. Both are now
>> released as Tree::Range 0.1. The CPAN page for the version is:
>> http://search.cpan.org/~onegray/Tree-Range-0.1/
>> PS. The namespace registration request is filed and pending
>> approval.
> The namespace registration process is pretty-much defunct at this
> point. Both Tree::Range::RB and Tree::Range::base are already as
> 'properly registered' as they need to be; that is, they are listed in
> 02packages.details.txt.gz on CPAN, so clients like CPAN.pm and cpanm
> will find your distributions for those package names.
Yes.
Still, it's recommended by [1] (though feel free to file a bug
report if you think it shouldn't be):
[...] A registration is not a prerequisite for uploading. It is
just recommended for better searchability of the CPAN and to avoid
namespace clashes. [...]
Besides, it'll add some useful bits of information to [2].
[1] https://pause.perl.org/pause/authenquery?ACTION=apply_mod
[2] http://search.cpan.org/~onegray/
> However, it goes against convention to have a distribution called
> Tree-Range that does not contain a module Tree::Range. You should
> consider either renaming Tree::Range::base
Won't this go against the example set by Digest::base? (which I
tend to think as a good enough to stick to.)
> or at least providing a documentation-only Tree::Range explaining why
> there isn't a module there.
I guess I'd consider the latter for 0.2. (Which I hope'll be
the release fixing only the documentation and the metadata.)
The other option would be to have Tree::Range->new () behave
like Digest->new ().
--
FSF associate member #7257
------------------------------
Date: Thu, 27 Jun 2013 11:24:35 +0100
From: Ben Morrow <ben@morrow.me.uk>
Subject: Re: Tree::Range 0.1 released
Message-Id: <3ggt9a-22b2.ln1@anubis.morrow.me.uk>
Quoth Ivan Shmakov <oneingray@gmail.com>:
> >>>>> Ben Morrow <ben@morrow.me.uk> writes:
>
> > The namespace registration process is pretty-much defunct at this
> > point. Both Tree::Range::RB and Tree::Range::base are already as
> > 'properly registered' as they need to be; that is, they are listed in
> > 02packages.details.txt.gz on CPAN, so clients like CPAN.pm and cpanm
> > will find your distributions for those package names.
>
> Yes.
>
> Still, it's recommended by [1] (though feel free to file a bug
> report if you think it shouldn't be):
>
> [...] A registration is not a prerequisite for uploading. It is
> just recommended for better searchability of the CPAN and to avoid
> namespace clashes. [...]
See <https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/
lancaster-consensus.md#module-registration> (and indeed the rest of that
document). While this is a 'new' agreement, in the Perl world agreements
and specs usually come after implementation, so it is describing the
way things currently work in practice.
> Besides, it'll add some useful bits of information to [2].
...which noone but you will ever look at :).
> > However, it goes against convention to have a distribution called
> > Tree-Range that does not contain a module Tree::Range. You should
> > consider either renaming Tree::Range::base
>
> Won't this go against the example set by Digest::base? (which I
> tend to think as a good enough to stick to.)
It's not a convention I've seen before, but there's nothing wrong with
it. (It would be more usual to be ::Base, at least; the analogy with
base.pm is not really relevant any more.)
> > or at least providing a documentation-only Tree::Range explaining why
> > there isn't a module there.
>
> I guess I'd consider the latter for 0.2. (Which I hope'll be
> the release fixing only the documentation and the metadata.)
>
> The other option would be to have Tree::Range->new () behave
> like Digest->new ().
Yeah, perhaps. I haven't really got a sense of what this module's useful
for, so I can't comment.
Ben
------------------------------
Date: Thu, 27 Jun 2013 11:05:31 +0000
From: Ivan Shmakov <oneingray@gmail.com>
Subject: Re: Tree::Range 0.1 released
Message-Id: <87a9mb95l0.fsf@violet.siamics.net>
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
[...]
>> Still, it's recommended by [1] (though feel free to file a bug
>> report if you think it shouldn't be):
>> [...] A registration is not a prerequisite for uploading. It is
>> just recommended for better searchability of the CPAN and to avoid
>> namespace clashes. [...]
> See <https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/
> master/lancaster-consensus.md#module-registration> (and indeed the
> rest of that document). While this is a 'new' agreement, in the Perl
> world agreements and specs usually come after implementation, so it
> is describing the way things currently work in practice.
So, I guess [1] is going to be updated within a few months from
now. Thanks.
>> [1] https://pause.perl.org/pause/authenquery?ACTION=apply_mod
[...]
>>> However, it goes against convention to have a distribution called
>>> Tree-Range that does not contain a module Tree::Range. You should
>>> consider either renaming Tree::Range::base
>> Won't this go against the example set by Digest::base? (which I tend
>> to think as a good enough to stick to.)
> It's not a convention I've seen before, but there's nothing wrong
> with it. (It would be more usual to be ::Base, at least; the analogy
> with base.pm is not really relevant any more.)
AIUI, the "capital-case" names under Digest:: are reserved for
the actual message digest algorithms. For instance,
Digest->new ("SHA-1") ends up in a call to Digest::SHA->new (1).
>>> or at least providing a documentation-only Tree::Range explaining
>>> why there isn't a module there.
>> I guess I'd consider [it] for 0.2. (Which I hope'll be the release
>> fixing only the documentation and the metadata.)
>> The other option would be to have Tree::Range->new () behave like
>> Digest->new ().
> Yeah, perhaps. I haven't really got a sense of what this module's
> useful for, so I can't comment.
One of the possible uses of Tree::Range::RB specifically is to
operate on .newsrc data. Consider, e. g.:
### gxmj7tsetytsnbnp85yhxyjror.perl -*- Perl -*-
### Ivan Shmakov, 2013
### Code:
use common::sense;
require Tree::Range::RB;
sub ranges_parse {
my ($in, @ranges) = @_;
foreach my $range (@ranges) {
my ($a, $b)
= ($range =~ /^([0-9]+)(?:-([0-9]+))?$/)
or die ($range, ": is not a vaild range");
$in->range_set ($a, 1 + ($b // $a), 1);
}
## .
$in;
}
my @comp_lang_perl_misc_s = qw {
1-27551 27567 27575 27602-27606 27627-27629 27632 27634-27636
27638-27996
27998-28002 28004 28006-28008 28011-28013 28015-28027 28029 28032
28036-28093
};
my $comp_lang_perl_misc
= Tree::Range::RB->new ({ "cmp" => sub { $_[0] <=> $_[1]; },
"equal-p" => sub { $_[0] eq $_[1]; } });
ranges_parse ($comp_lang_perl_misc, @comp_lang_perl_misc_s);
{
local ($,, $\)
= (", ", "\n");
## check if 28007 was read? (i. e., what range 28007 belongs to?)
print ($comp_lang_perl_misc->get_range (28007));
## => 1, 28006, 28009
## now the user has marked some more articles as read
ranges_parse ($comp_lang_perl_misc, qw (28005 28009 28010));
## check if 28011 was read? (i. e., what range 28011 belongs to?)
print ($comp_lang_perl_misc->get_range (28011));
## => 1, 28004, 28014
## note how the range was extended as the gaps were filled
}
### gxmj7tsetytsnbnp85yhxyjror.perl ends here
Similarly, by utilizing the Tree::RB's own iterator, a simple
and efficient serializer for this kind of data can be built.
--
FSF associate member #7257
------------------------------
Date: Thu, 27 Jun 2013 12:50:48 +0100
From: Ben Morrow <ben@morrow.me.uk>
Subject: Re: Tree::Range 0.1 released
Message-Id: <ohlt9a-upb2.ln1@anubis.morrow.me.uk>
Quoth Ivan Shmakov <oneingray@gmail.com>:
>
> One of the possible uses of Tree::Range::RB specifically is to
> operate on .newsrc data. Consider, e. g.:
>
>
> my @comp_lang_perl_misc_s = qw {
> 1-27551 27567 27575 27602-27606 27627-27629 27632 27634-27636
> 27638-27996
> 27998-28002 28004 28006-28008 28011-28013 28015-28027 28029 28032
> 28036-28093
> };
>
> my $comp_lang_perl_misc
> = Tree::Range::RB->new ({ "cmp" => sub { $_[0] <=> $_[1]; },
> "equal-p" => sub { $_[0] eq $_[1]; } });
> ranges_parse ($comp_lang_perl_misc, @comp_lang_perl_misc_s);
>
> {
> local ($,, $\)
> = (", ", "\n");
>
> ## check if 28007 was read? (i. e., what range 28007 belongs to?)
> print ($comp_lang_perl_misc->get_range (28007));
> ## => 1, 28006, 28009
>
> ## now the user has marked some more articles as read
> ranges_parse ($comp_lang_perl_misc, qw (28005 28009 28010));
Is this importantly different from Set::IntSpan/::Fast/::XS?
Ben
------------------------------
Date: Thu, 27 Jun 2013 13:11:19 +0000
From: Ivan Shmakov <oneingray@gmail.com>
Subject: Re: Tree::Range 0.1 released
Message-Id: <871u7n8zrc.fsf@violet.siamics.net>
>>>>> Ben Morrow <ben@morrow.me.uk> writes:
>>>>> Quoth Ivan Shmakov <oneingray@gmail.com>:
>> One of the possible uses of Tree::Range::RB specifically is to
>> operate on .newsrc data. Consider, e. g.:
[...]
>> my $comp_lang_perl_misc
>> = Tree::Range::RB->new ({ "cmp" => sub { $_[0] <=> $_[1]; },
>> "equal-p" => sub { $_[0] eq $_[1]; } });
[...]
>> print ($comp_lang_perl_misc->get_range (28007));
>> ## => 1, 28006, 28009
[...]
> Is this importantly different from Set::IntSpan/::Fast/::XS?
Yes, although not in the case of .newsrc.
First of all, each range (span, interval, etc.) may have an
associated value. It's "1" (or "undef", for the "complementary"
ranges) in the example above, but it needs not to be.
Moreover, unlike Set::IntSpan, Tree::Range::RB is applicable to
an arbitrary ordered set. (Note the "cmp" option above.)
Also, having Set::IntSpan (and Set::IntSpan::Fast, as per the
documentation) implemented on top of an ordered list seems to
imply the insertion and deletion times of O (N), while for a
red-black tree they're both O (log N). Though ::XS may still
outperform a pure-Perl tree-based implementation on reasonable
use cases.
--
FSF associate member #7257
------------------------------
Date: 6 Apr 2001 21:33:47 GMT (Last modified)
From: Perl-Users-Request@ruby.oce.orst.edu (Perl-Users-Digest Admin)
Subject: Digest Administrivia (Last modified: 6 Apr 01)
Message-Id: <null>
Administrivia:
To submit articles to comp.lang.perl.announce, send your article to
clpa@perl.com.
Back issues are available via anonymous ftp from
ftp://cil-www.oce.orst.edu/pub/perl/old-digests.
#For other requests pertaining to the digest, send mail to
#perl-users-request@ruby.oce.orst.edu. Do not waste your time or mine
#sending perl questions to the -request address, I don't have time to
#answer them even if I did know the answer.
------------------------------
End of Perl-Users Digest V11 Issue 3975
***************************************
