in reply to Re^5: POD Standards
in thread POD Standards

As a for instance, if you do not already know which core document CHECK{} blocks are documented in, try finding it:

P:\test>perldoc

I don't get it what you are trying to prove. perldoc doesn't search (except for the faq), nor does it do an index lookup yet (except for functions). It's pod doesn't claim that it does. Once you've learned that, you wouldn't ever try any of that again. In fact, I'd hope you'd do perldoc perldoc and not even bother in the first place.

Something that does work? Look at perltoc, search for CHECK, go to the indicated page (perlmod). If that doesn't work, use an actual search tool.

That said, work is being done to add X<> indexing tags to the core pods; I'd hope perldoc would take advantage of them someday soon.

Replies are listed 'Best First'.
Re^7: POD Standards
by BrowserUk (Patriarch) on Jan 08, 2006 at 13:31 UTC

    I'm not trying to prove anything.

    I'm trying to show that whilst the information contained within the current documentation set is generally very good. All of the time and effort that went into producing and maintaining that information is let down by the inadaquate means of locating the information you require. If you know where to look, you know; but if you don't, you are stymied.

    Manually produced indexes are no substitute for machine generated TOCs and indexes.

    And grepping your entire perl installation is no substitute either. Being quite selective about what I grepped, a search for "CHECK" turns up 288 references spread across 67 files. Most of those are embedded within html markup which makes trying to subset the list visually, very difficult.

    But mostly, I gave the OP an alternate viewpoint to his question, and posted a little justification for why I arrived at that alternate viewpoint in direct response to questions asked of me.

    If POD has merit, then it can surely stand up to a little scrutiny?

    I don't consider that it does stand up to scrutiny and for me, both defenses of POD--your "use a proper [...] tool", and jZed's "but there is POD::PseudoPod"--better confirm ('prove') my conclusions than anything I could have said.

    However, with the information available, the OP can and will make up his mind what is correct for his purposes. Whichever way he chooses to go, the provision of the alternative viewpoint will not have harmed his decision making process.

    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
    "Science is about questioning the status quo. Questioning authority".
    In the absence of evidence, opinion is indistinguishable from prejudice.
[reply]
      I don't consider that it does stand up to scrutiny and for me, both defenses of POD--your "use a proper [...] tool",
      Just to clarify, I wasn't trying to defend Pod, I was trying to defend perldoc. Pod is a file format, and as such doesn't really have a designated user interface. You are perfectly free to brew your own.
[reply]

In Section Meditations