Re^3: How perldoc chooses PODs' path

Generating file.pod in a way reflecting these needs could be a handy solution, w/o forcing anybody to use anything else than classical perlpod.

I’m afraid you’ve lost me there. I suppose I do occasionally use pod2text, usually on a exact pathname, sometimes in conjunction with pmpath to find a module path. Isn’t pod2text the classic program here? Why bother with anything else?

I honestly can’t think of any reason (apart from being trapped on Windows, I suppose) why anyone would use anything but the normal man program for reading Perl documentation. Occasionally I create PDF or HTML, but those are pretty special-purposed.

I have a bunch of little tools for dealing with modules and with pod. Here’s a partial list: balance-angles, balance-braces, balance-brackets, balance-parens, balanced, basepods, catpod, catpodidx, faqpods, fmtpara, idxspell, modpods, okpod, ora2pod, orphanX, pmall, pmcat, pmdesc, pmdirs, pmeter, pmeth, pmexp, pmfunc, pminst, pmload, pmls, pmman, pmpath, pmvers, pod2docbook, pod2ora, podcode, podgrep, podpath, pods, podtoc, shflpod, sitepods, splitpod, stdpods, testpod, uniwc, xfootnotes, and xpod — just to name a few.

Here’s an illustration of the way I mix and match just a few of the more frequently used ones:


  % 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.p
+m
     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

  % 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} = s
+hift; }
            else                                { $classical{$arg} = 1
+;     }

            if ($arg eq 'all') {
                %classical = $classical{all} ? %all_classical : ();
            }
        }
    }

  % pmexp File::Basename
    File::Basename automatically exports fileparse, fileparse_set_fsty
+pe, 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_A
+DJ_eq, PART_PRES, ORD, NUMWORDS, WORDLIST, def_noun, def_verb, def_ad
+j, def_a, and def_an
    Lingua::EN::Inflect export tag `ARTICLES' includes classical, infl
+ect, NUM, A, and AN
    Lingua::EN::Inflect export tag `COMPARISONS' includes classical, P
+L_eq, PL_N_eq, PL_V_eq, and PL_ADJ_eq
    Lingua::EN::Inflect export tag `INFLECTIONS' includes classical, i
+nflect, 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 NUMWOR
+DS
    Lingua::EN::Inflect export tag `PLURALS' includes classical, infle
+ct, 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, d
+ef_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 o
+r 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.p
+m
    /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/Ra
+w/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.p
+m
    /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.p
+m
    /usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/File/Glob.p
+m
    /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/Alia
+s.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/Conf
+ig.pm
    /usr/local/lib/perl5/5.13.0/IO/Uncompress/Base.pm
    /usr/local/lib/perl5/5.13.0/darwin-thread-multi-2level/Encode/Enco
+ding.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/Storab
+le/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/U
+nix.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_heav
+y.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/H
+TML/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.p
+m
    /usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/H
+TML/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/H
+TML/TokeParser.pm
    /usr/local/lib/perl5/site_perl/5.13.0/darwin-thread-multi-2level/H
+TML/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/Compre
+ss/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
[download]

But for just reading things, I always use pod2text on uninstalled things and man on installed things. Anything else just gets in my way — but your mileage may vary, especially if you’ve been metricated. 😈

Comment on Re^3: How perldoc chooses PODs' path Download Code

Replies are listed 'Best First'.
Re^4: How perldoc chooses PODs' path by LanX (Saint) on Mar 02, 2012 at 00:04 UTC
Your pmtools are really nice! (Especially for analyzing PMs and PODs). Thanks for showing me! :) But my aim is rather to have an easier (and more DRY) way to author POD (and BTW docstrings for introspection) Cheers Rolf	[reply]
Re^4: How perldoc chooses PODs' path by BrowserUk (Patriarch) on Mar 02, 2012 at 00:13 UTC
I honestly can’t think of any reason (apart from being trapped on Windows, I suppose) why anyone would use anything but the normal man program for reading Perl documentation. And I honestly cannot think of any reason (apart from the living nightmare of Life on Mars ) why anyone would use `man`. Or perldoc. Or POD for that matter. Hey. Perhaps there is a market for a new website: say, TWinders.com. It'd be like Twitter, but use smoke signals for the last mile. For all those ol'fogies out there than can't bring themselves to move beyond the golden days of their youth. With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday' Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. "Science is about questioning the status quo. Questioning authority". In the absence of evidence, opinion is indistinguishable from prejudice. The start of some sanity?	[reply] [d/l]
Re^5: How perldoc chooses PODs' path by LanX (Saint) on Mar 02, 2012 at 00:23 UTC
> why anyone would use man. indeed info is much nicer... Cheers Rolf	[reply]