Front page | perl.perl5.porters |
Postings from March 2011
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a new OO tutorial)
Thread Previous
|
Thread Next
From:
Tom Christiansen
Date:
March 4, 2011 11:55
Subject:
Re: Rethinking some perldocs (Re: Revising Perl's OO docs - a new OO tutorial)
Message ID:
9343.1299268546@chthon
Matt Sergeant <matt@sergeant.org> wrote:
> Tom Christiansen wrote:
>> What in the world would I type 10 characters instead of 3???
>(*Why, I assume)
Yes.
> Because there is no "man" equivalent of "perldoc -f".
Sure there is. Did you forget to run splitpod?
The functions are in section 3. Of course.
> Because there is no "man" equivalent of "perldoc -q" (yes I
> don't use it personally either, but I *do* refer newbies to the
> FAQ pages, which still requires making sure the query finds
> what they need to know)
See below.
> Because there's no "man" equivalent of "perldoc -m"
Bah.
% pmpath Lingua::EN::Inflect
/usr/local/lib/perl5/site_perl/5.12.2/Lingua/EN/Inflect.pm
% pmcat Lingua::EN::Inflect | grep -c '^sub\b'
42
% catpod `pmpath Lingua::EN::Inflect` | grep -c '^=\w'
71
% catpod perl-git/*.c | grep -c apidoc
78
% podgrep api perl-git/av.c
=head1 av.c chunk 70
=for apidoc av_create_and_push
=head1 av.c chunk 89
=for apidoc av_create_and_unshift_one
% stdpods | wc -l
595
% sitepods | wc -l
5533
% podtoc `pmpath File::Spec`
/usr/local/lib/perl5/5.12.3/darwin-thread-multi-2level/File/Spec.pm
NAME
SYNOPSIS
DESCRIPTION
METHODS
* canonpath
* catdir
* catfile
* curdir
* devnull
* rootdir
* tmpdir
* updir
* no_upwards
* case_tolerant
* file_name_is_absolute
* path
* join
* splitpath
* splitdir
* catpath()
* abs2rel
* rel2abs()
SEE ALSO
AUTHOR
COPYRIGHT
% pmdirs
/usr/local/lib/perl5/site_perl/5.12.3/darwin-thread-multi-2level
/usr/local/lib/perl5/site_perl/5.12.3
/usr/local/lib/perl5/5.12.3/darwin-thread-multi-2level
/usr/local/lib/perl5/5.12.3
/usr/local/lib/perl5/site_perl/5.12.2/darwin-thread-multi-2level
/usr/local/lib/perl5/site_perl/5.12.2
/usr/local/lib/perl5/site_perl/5.11.3
/usr/local/lib/perl5/site_perl/5.10.0
/usr/local/lib/perl5/site_perl
.
% pmls Pod::PseudoPod
-r--r--r-- 1 root wheel 17809 Jun 18 2009 /usr/local/lib/perl5/site_perl/5.10.0/Pod/PseudoPod.pm
% pmls feature
-r--r--r-- 1 root wheel 5863 Feb 14 07:36 /usr/local/lib/perl5/5.12.3/feature.pm
% pmls version
-r--r--r-- 1 root wheel 6494 Dec 19 13:15 /usr/local/lib/perl5/site_perl/5.12.3/darwin-thread-multi-2level/version.pm
> Because man can't read the pod prettily in a local file.
Yeah, right.
% pod2text `pmpath Lingua::EN::Inflect`
% pod2man `pmpath Lingua::EN::Inflect` | groff -mandoc -Tps
% pmvers Lingua::EN::Inflect
1.893
% pmeth File::Basename
_strip_trailing_sep
basename
dirname
fileparse
fileparse_set_fstype
as_heavy via Exporter
export via Exporter
export_fail via Exporter
export_ok_tags via Exporter
export_tags via Exporter
export_to_level via Exporter
import via Exporter
require_version via Exporter
DOES via UNIVERSAL
VERSION via UNIVERSAL
can via UNIVERSAL
[overridden] import via UNIVERSAL
isa via UNIVERSAL
% pmfunc Lingua::EN::Inflect::classical
sub classical
{
if (!@_) {
%classical = %all_classical;
return;
}
if (@_==1 && $_[0] !~ $classical_mode) {
%classical = $_[0] ? %all_classical : ();
return;
}
while (@_) {
my $arg = shift;
if ($arg !~ $classical_mode) {
die "Unknown classical mode ($arg)\n";
}
if (@_ && $_[0] !~ $classical_mode) { $classical{$arg} = shift; }
else { $classical{$arg} = 1; }
if ($arg eq 'all') {
%classical = $classical{all} ? %all_classical : ();
}
}
}
% pmexp File::Basename
File::Basename automatically exports fileparse, fileparse_set_fstype, basename, and dirname
% pmexp Carp
Carp automatically exports confess, croak, and carp
Carp optionally exports cluck, verbose, longmess, and shortmess
% pmexp Lingua::EN::Inflect
Lingua::EN::Inflect optionally exports classical, inflect, PL, PL_N, PL_V, PL_ADJ, NO, NUM, A, AN, PL_eq, PL_N_eq, PL_V_eq, PL_ADJ_eq, PART_PRES, ORD, NUMWORDS, WORDLIST, def_noun, def_verb, def_adj, def_a, and def_an
Lingua::EN::Inflect export tag `ALL' includes classical, inflect, PL, PL_N, PL_V, PL_ADJ, NO, NUM, A, AN, PL_eq, PL_N_eq, PL_V_eq, PL_ADJ_eq, PART_PRES, ORD, NUMWORDS, WORDLIST, def_noun, def_verb, def_adj, def_a, and def_an
Lingua::EN::Inflect export tag `ARTICLES' includes classical, inflect, NUM, A, and AN
Lingua::EN::Inflect export tag `COMPARISONS' includes classical, PL_eq, PL_N_eq, PL_V_eq, and PL_ADJ_eq
Lingua::EN::Inflect export tag `INFLECTIONS' includes classical, inflect, PL, PL_N, PL_V, PL_ADJ, PL_eq, NO, NUM, A, AN, and PART_PRES
Lingua::EN::Inflect export tag `NUMERICAL' includes ORD and NUMWORDS
Lingua::EN::Inflect export tag `PLURALS' includes classical, inflect, PL, PL_N, PL_V, PL_ADJ, NO, NUM, PL_eq, PL_N_eq, PL_V_eq, and PL_ADJ_eq
Lingua::EN::Inflect export tag `USER_DEFINED' includes def_noun, def_verb, def_adj, def_a, and def_an
% pminst | head
version
Lingua::Stem::Snowball
String::Approx
Term::ReadLine::Gnu
Term::ReadLine::Gnu::XS
CPAN::Meta::YAML
ExtUtils::CBuilder
ExtUtils::CBuilder::Base
ExtUtils::CBuilder::Platform::aix
ExtUtils::CBuilder::Platform::cygwin
% pminst Lingua::EN
Lingua::EN::Numbers
Lingua::EN::Inflect
Lingua::EN::Segmenter
Lingua::EN::Splitter
Lingua::EN::StopWords
Lingua::EN::Segmenter::Baseline
Lingua::EN::Segmenter::Evaluator
Lingua::EN::Segmenter::TextTiling
Lingua::EN::Numbers::Ordinate
5.10.0::Lingua::EN::Numbers::Ordinate
5.12.2::Lingua::EN::Inflect
5.12.2::Lingua::EN::Segmenter
5.12.2::Lingua::EN::Splitter
5.12.2::Lingua::EN::StopWords
5.12.2::Lingua::EN::Segmenter::Baseline
5.12.2::Lingua::EN::Segmenter::Evaluator
5.12.2::Lingua::EN::Segmenter::TextTiling
5.12.3::Lingua::EN::Numbers
5.13.0::Lingua::EN::Inflect
% pmdesc | head
Cwd (3.29) - get pathname of current working directory
DB_File (1.82) - Perl5 access to Berkeley DB version 1.x
Encode (2.33) - character encodings
encoding (2.6_01) - allows you to write your script in non-ascii or non-utf8
IO (1.23) - load various IO modules
Safe (2.16) - Compile and execute code in restricted compartments
Storable (2.18) - persistence for Perl data structures
threads (1.72) - Perl interpreter-based threads
XSLoader (0.10) - Dynamically load C libraries into Perl code
B::Debug (1.11) - Walk Perl syntax tree, printing debug info about ops
% pmload IO::Handle
/usr/local/lib/perl5/5.12.3/XSLoader.pm
/usr/local/lib/perl5/5.12.3/Carp.pm
/usr/local/lib/perl5/5.12.3/darwin-thread-multi-2level/IO/Handle.pm
/usr/local/lib/perl5/5.12.3/Exporter.pm
/usr/local/lib/perl5/5.12.3/strict.pm
/usr/local/lib/perl5/5.12.3/SelectSaver.pm
/usr/local/lib/perl5/5.12.3/warnings.pm
/usr/local/lib/perl5/5.12.3/Symbol.pm
/usr/local/lib/perl5/5.12.3/darwin-thread-multi-2level/IO.pm
% pmload WWW::Mechanize
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Compress/Raw/Zlib.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Status.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/List/Util.pm
/usr/local/lib/perl5/5.13.0/IO/Uncompress/Adapter/Inflate.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Fcntl.pm
/usr/local/lib/perl5/5.13.0/Symbol.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Scalar/Util.pm
/usr/local/lib/perl5/site_perl/5.13.0/URI.pm
/usr/local/lib/perl5/5.13.0/Exporter.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/File/Spec.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/File/Glob.pm
/usr/local/lib/perl5/5.13.0/File/GlobMapper.pm
/usr/local/lib/perl5/5.13.0/warnings/register.pm
/usr/local/lib/perl5/5.13.0/XSLoader.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Gzip.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode/Alias.pm
/usr/local/lib/perl5/site_perl/5.11.3/HTML/Tagset.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode/Config.pm
/usr/local/lib/perl5/5.13.0/IO/Uncompress/Base.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode/Encoding.pm
/usr/local/lib/perl5/site_perl/5.13.0/LWP/MemberMixin.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Config_git.pl
/usr/local/lib/perl5/5.13.0/utf8.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/auto/Storable/autosplit.ix
/usr/local/lib/perl5/5.13.0/IO/Uncompress/Gunzip.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTML/Form.pm
/usr/local/lib/perl5/5.13.0/bytes.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/File/Spec/Unix.pm
/usr/local/lib/perl5/5.13.0/Exporter/Heavy.pm
/usr/local/lib/perl5/5.13.0/vars.pm
/usr/local/lib/perl5/5.13.0/strict.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Request.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Config_heavy.pl
/usr/local/lib/perl5/5.13.0/IO/Compress/Base.pm
/usr/local/lib/perl5/5.13.0/AutoLoader.pm
/usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/HTML/Entities.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Headers.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Zlib/Extra.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Storable.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/IO/Handle.pm
/usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/HTML/Parser.pm
/usr/local/lib/perl5/site_perl/5.13.0/WWW/Mechanize.pm
/usr/local/lib/perl5/5.13.0/SelectSaver.pm
/usr/local/lib/perl5/5.13.0/Compress/Zlib.pm
/usr/local/lib/perl5/5.13.0/Time/Local.pm
/usr/local/lib/perl5/5.13.0/warnings.pm
/usr/local/lib/perl5/site_perl/5.13.0/LWP/UserAgent.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Date.pm
/usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/HTML/TokeParser.pm
/usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/HTML/PullParser.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Response.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Gzip/Constants.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/RawDeflate.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Adapter/Deflate.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/auto/Compress/Raw/Zlib/autosplit.ix
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/IO/Seekable.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode.pm
/usr/local/lib/perl5/5.13.0/base.pm
/usr/local/lib/perl5/5.13.0/IO/Uncompress/RawInflate.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Config.pm
/usr/local/lib/perl5/site_perl/5.13.0/LWP.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/IO.pm
/usr/local/lib/perl5/5.13.0/Carp.pm
/usr/local/lib/perl5/site_perl/5.13.0/HTTP/Message.pm
/usr/local/lib/perl5/5.13.0/FileHandle.pm
/usr/local/lib/perl5/5.13.0/IO/Compress/Base/Common.pm
/usr/local/lib/perl5/5.13.0/constant.pm
/usr/local/lib/perl5/site_perl/5.13.0/LWP/Protocol.pm
/usr/local/lib/perl5/5.13.0/overload.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/IO/File.pm
/usr/local/lib/perl5/site_perl/5.13.0/URI/Escape.pm
/usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/DynaLoader.pm
(Some people don't know what they're getting into, I see.)
> Because you can alias perldoc to "pd" if you want to, so a number of
> characters argument is silly.
I like using things I know how work.
> Because man can't deal with documentation from multiple perl installations.
Of course it can. You just have to know how to set up correctly.
> There are plenty of reasons to prefer perldoc to man.
As soon as perldoc can do ALL OF WHAT I ALREADY DO *AND MORE*,
then and only then shall I consider it.
Until then, there is no reason for me to regress to such an
embarrassing primitive tool when I have an entire toolbox at
my fingertips, one infinite in variation.
Those who ignore Unix are doomed to repeat it. Badly.
--tom
Thread Previous
|
Thread Next