develooper 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


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About