Re^5: POD Standards

I just use a half-dozen line pod.cgi or pseudopod.cgi

Which means that everyone who wants to read the documentation has to be running a webserver.

And every time anyone wants to read a document, it has to be reparsed. Over and over all over the world.

And that pre-supposes that you know which document contains the information you need. If you come across an unfamiliar language construct in someone elses source code, there are about twenty different places you might find the relevant documentation. Once you found it, the documentation is generally quite good, and well maintained. But finding it? Oh boy!

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

P:\test>perldoc CHECK
No documentation found for "CHECK".

P:\test>perldoc /f CHECK
No documentation found for "/f".
No documentation found for "CHECK".

P:\test>perldoc -f CHECK
No documentation for perl function `CHECK' found

P:\test>perldoc -q CHECK
Found in C:\Perl\lib\pod\perlfaq4.pod
  How do I verify a credit card checksum?
    Get the Business::CreditCard module from CPAN.

Found in C:\Perl\lib\pod\perlfaq8.pod
  How do I check whether input is ready on the keyboard?
    The easiest way to do this is to read a key in nonblocking mode wi
+th the
    Term::ReadKey module from CPAN, passing it an argument of -1 to in
+dicate
    not to block:

        use Term::ReadKey;

        ReadMode('cbreak');

        if (defined ($char = ReadKey(-1)) ) {
            # input was waiting and it was $char
        } else {
            # no input was waiting
        }

        ReadMode('normal');                  # restore normal tty sett
+ings

Found in C:\Perl\lib\pod\perlfaq9.pod
  How do I check a valid mail address?
    You can't, at least, not in real time. Bummer, eh?

    Without sending mail to the address and seeing whether there's a h
+uman
[SNIP]
[download]

There are many more examples.

Even once converted to html per AS docs, there is still no easy way to find where in the IO::Socket::INET docs the recv call is documented. Or where in the LWP::* suite you should look to find the numeric/text mapping for HTTP error codes.

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.

Comment on Re^5: POD Standards Download Code

Replies are listed 'Best First'.
Re^6: POD Standards by ysth (Canon) on Jan 08, 2006 at 12:33 UTC
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.	[reply] [d/l]
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]
Re^8: POD Standards by ysth (Canon) on Jan 08, 2006 at 13:41 UTC
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]
Re^6: POD Standards by jZed (Prior) on Jan 06, 2006 at 22:15 UTC
Ok, point taken, you're right, POD's not perfect. What do you use instead?	[reply]
Re^7: POD Standards by Perl Mouse (Chaplain) on Jan 07, 2006 at 00:12 UTC
I use three types of documentation: POD, mostly for Perl (and C and shell) programs, and only to generate manual pages from. LaTeX for most things that exceeds manual pages (long time ago, I used to use roff and friends for that). And plain ASCII for anything else (and that's quite a lot). But to solve the problem of finding the right documentation, you need an index. (La)TeX is good in generating indices. `Perl --((8:>`	[reply]
Re^7: POD Standards by BrowserUk (Patriarch) on Jan 06, 2006 at 22:22 UTC
In previous lives, HTML and a decent html editor. If I were starting a project tomorrow, it would be doxygen. 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]