CPAN vs. POD outside of .pm (.pl) files?

[Rainer Weikusat]

[...]

Unless this moves again into a different direction, I'm going to
ignore it. I'm interested in programming problems, here, programming
problems specifically relating to Perl, and not in this kind of "who's
the most fastly rotating humming top" 'system architecture theory
wars' (this is not supposed to be offensive, I just see no value in
such a discussion).

 

[Mart van de Wege]

However, once you start installing modules directly from CPAN (which I
don't recommend with an OS-installed perl in any case), or developing
your own, you start to find that Perl developers assume 'perl vX means
you have module Y in core', or 'header H', or 'Unicode data file U',
and these assumptions no longer necessarily hold.

I am speaking from the background of rather a lot of bug reports which
end up like this

'...I don't have ___.'
'You ought to, it's in the core.'
'...Oh, right, my OS package doesn't include that...'

not to mention the 'but perldoc doesn't work' people we get here from
time to time.

Which is why Debian has helper tools to create your own packages from
CPAN modules.

In case of most modules, a CPAN module can be installed with one
command. The only thing it doesn't do yet is automatic dependency
management, but that is something you don't get with manual installs
either.

And perldoc is a bit of a red herring. Debian users know that Debian
doesn't package docs by default and will see it is a 'Suggested'
package, so they can install it when needed.

The problem is Debian derivatives that stupidly install a subset of
Debian packages without looking at the Suggests for their default build,
and then sell themselves as a ready-made solution for the (beginning)
Linux developer. Yes, I do mean Ubuntu.

Mart

 

[Dave Saville]

Which is why Debian has helper tools to create your own packages from
CPAN modules.

In case of most modules, a CPAN module can be installed with one
command. The only thing it doesn't do yet is automatic dependency
management, but that is something you don't get with manual installs
either.

And perldoc is a bit of a red herring. Debian users know that Debian
doesn't package docs by default and will see it is a 'Suggested'
package, so they can install it when needed.

The problem is Debian derivatives that stupidly install a subset of
Debian packages without looking at the Suggests for their default build,
and then sell themselves as a ready-made solution for the (beginning)
Linux developer. Yes, I do mean Ubuntu.

I just fell over that one with Ubuntu and I was going to ask sometime.
I am not a great fan of Ubuntu so what distro do you perl hackers
recommend so *I* get control of such things?

TIA

 

[Ivan Shmakov]

[...]

This subthread started with a Debian user who didn't know that.

Even though I think I've clarified this thing up in [1], I'd
like to reiterate it once more: I knew about the perl-doc
package since well before this discussion, and it was indeed the
first package for me to look for "command-line perldoc."

My point was that I never used the latter, and I feel no loss of
that, or an urge to start using it, like, now.

[1]
[...]

PS. And should anyone ask my advice about reading Perl documentation,
it's highly unlikely that perldoc(1) would come to my mind as
something deserving a mention.

 

[Rainer Weikusat]

[...]

PS. And should anyone ask my advice about reading Perl documentation,
it's highly unlikely that perldoc(1) would come to my mind as
something deserving a mention.

perldoc -f is quite useful for looking up descriptions of individual
builtin functions/operators. I also perldoc -q, although less
frequently.

 

[Ivan Shmakov]

Ivan Shmakov <[email protected]> writes: [...]

PS. And should anyone ask my advice about reading Perl
documentation, it's highly unlikely that perldoc(1) would come to my
mind as something deserving a mention.

perldoc -f is quite useful for looking up descriptions of individual
builtin functions/operators.

How is it different to pointing one's browser at, say,
http://perldoc.perl.org/functions/NAME.html?

I also perldoc -q, although less frequently.

Indeed, a sensible application. (And it certainly looks like a
kind of a "structured" search facility.)

But what makes me wonder is: was it added to work-around the
whole issue of the Perl FAQ being split into several manpages?

 

[Jürgen Exner]

How is it different to pointing one's browser at, say,
http://perldoc.perl.org/functions/NAME.html?

There is no need for an additional tool, i.e. a browser. There is no
need for an Internet connection. And the documentation is actually
matching the version of Perl that I am using.

jue

 

[Ivan Shmakov]

[...]

There is no need for an additional tool, i. e. a browser.

For me, it's perldoc(1) that's an "additional" tool.

There is no need for an Internet connection.

Indeed. However, a developer is likely to have one, anyway.

And the documentation is actually matching the version of Perl that I
am using.

OTOH, the documentation packaged with the version of Perl used
may still have bugs already resolved in the newer version served
from http://perldoc.perl.org/.

 

[Peter J. Holzer]

There is no need for an additional tool, i.e. a browser. There is no
need for an Internet connection. And the documentation is actually
matching the version of Perl that I am using.

And it works for all perl-related stuff I have installed: Perl core,
CPAN modules, modules and scripts developed in-house ...

http://perldoc.perl.org/ only covers the core. HTML-formatted docs for
CPAN modules are on http://search.cpan.org. And your own stuff is
whereever you (or your co-workers) put it. So that's at least three
different places. With perldoc it's only one.

hp

 

[Charlton Wilbur]

IS> How is [perldoc -f] different to pointing one's browser at, say,
IS> http://perldoc.perl.org/functions/NAME.html?

perldoc -f uses the perl documentation associated with your
installation. perldoc.perl.org takes extra steps and brainpower to
ensure that they match.

Charlton

 

[Rainer Weikusat]

How is it different to pointing one's browser at, say,
http://perldoc.perl.org/functions/NAME.html?

It prints a help message telling me that perldoc -f needs an argument
(and some other information) instead of 'The requested URL
/functions/NAME.html was not found on this server' (SCNR).

I consider it more convenient to use: It is easier to type than the
WWW-based version, it uses 'my default pager' whose search
facilities are more comfortable to use and more powerful than those of
firefox, it displays less stuff I don't care for and it is faster. It
is also more reliable because it works regardless of the conditions
'on the internet' ATM, using local computing facilities in order to
access the documentation is nicer to the people who generously provide
the perldoc WWW-service and - last but not least - it is better for
national security because it doesn't inject additional noise into
worlds largest and technically most sophiscated facility for storing
p0rn trailers and 'penis enlargment pills!' spam mails some very
duteous people built using tax payer's money so that they can sift
through all this trash to ensure that there are no terorists hiding
somewhere in it.

Possibly offensive content below the page break.

Also, imagine the frustation of someone who is one a holy mission to
locate child pornography who only ever gets Perl documentation. Surely
the cause of quite a few nervous breakdowns ...

 

[Eric Pozharski]

OTOH, the documentation packaged with the version of Perl used
may still have bugs already resolved in the newer version served
from http://perldoc.perl.org/.

See how I resist urge to post a troll-o-meter.

 

[Ivan Shmakov]

Content-type: text/plain; charset=UTF-8
[...]

Push the right button and Ben sounds like Rainer.

Touch\351 .

As for the pedantry, I'm curious, since when has a lone \351
acquired a defined meaning in UTF-8? (As opposed to:
ISO-8859-1.)

[...]

Well, I have to admit that this message is more a response to
(posted in
where I hereby cross-post), which I
haven't managed to answer back then, and do it now.

Newsgroups: soc.culture.russian, news.software.readers
From: Shmuel (Seymour J.) Metz <[email protected]>
Date: Wed, 05 Jun 2013 01:12:31 -0400
Subject: Re: [OT] Russian language

In <[email protected]>, Ivan Shmakov said:
[...]

Unfortunately, an RFC isn't a magic spell scroll to prevent
subscribers from using any of the non-compliant software, ever.

(And the last time I've checked, which was perhaps a decade ago,
though, trn had no MIME support whatsoever.)

That doesn't mean that the "American Usenet" (whatever that is) isn't
affected by the standards, or that there are a higher percentage of
nyekulturniy users in the USA than in Russia. Both counties have
people who follow the rules and people who don't.

My point is that it's not the /lack/ of culture, it's the people
who still adhere to the considerably older culture of "Usenet
without MIME."

PS. Not to mention that the "American Usenet" has seen an extra decade
of "MIME-less" operation as compared to the "Russian Usenet."