Re: An alternative Perldoc site

Replies are listed 'Best First'.
Re^2: An alternative Perldoc site by jj808 (Hermit) on Jan 21, 2005 at 14:32 UTC
Hi Merlyn, The http://perldoc.perldrunks.org site was designed from the start to be used off-line rather than on the web - you can download the complete mirror from http://perldoc.perldrunks.org/perldoc.tar.gz. See also the project page. I realise though that a good proportion of people won't be using Perl 5.8.6, so in the future I do plan to release the code to create the site from your local Perl installation. Cheers, JJ	[reply]
Re^2: An alternative Perldoc site by hossman (Prior) on Jan 21, 2005 at 19:06 UTC
The biggest advantage of offsite docs is that you don't have to have the module installed to read the docs, ou can acctaully read them first, and then decide if you want to install them. Not to mention that readign the docs for older versions of modules (or newer versions) can be very helpfull for understanding why someone else using an installation you don't have direct access to is getting different results; or to help you decide if you want to upgrade to the newest version of a distrobution. The argument can be made "just go download the distribution and then you can read the docs locally" ... but i find that argument very silly. Why does it make more sense to ask people to download a 1MB tar.gz just to read a single POD file then to download the same documentation as a 50KB html file?	[reply]
Re^2: An alternative Perldoc site by Limbic~Region (Chancellor) on Jan 21, 2005 at 19:40 UTC
merlyn, From my experience on #perl (Freenode), my biggest explanation for "on-line" documentation is the ability to search for what you are looking for. It doesn't help to have the documentation locally if you don't know what document you are looking for. Personally, I don't have any trouble using perldoc perltoc and perldoc -q "question" to help find what I want, but I have seen where the search function helped others. Admittedly, I have not played with my local documentation all that much to determine how easy/hard it would be to set up similar local functionality. Cheers - L~R	[reply]
Re^2: An alternative Perldoc site by Aristotle (Chancellor) on Jan 21, 2005 at 13:32 UTC
Two reasons: I haven't had the time to write a good POD-to-HTML converted to run across my local installation. `:-)` I wrote one once that worked decently, actually, but it indirectly depended on a bunch of modules I didn't want to keep and it had a few niggles of its own; rather than fix the latter, I trashed it in order to start fresh with a different set of the former; but I haven't gotten around to writing that replacement since. When I'm writing stuff on the web, I like to stick in hyperlinks for easy lookup for readers. It helps to have somewhere for the links to point to. grin That said I don't like that new site particularly much~~, nor do I like Kobe's rendition~~. The search.cpan.org look and featureset is exactly what I want/like. Update: actually, Kobesearch isn't as bad as I remember it; it had been a while since I went there. I still prefer the way the navigation is set up at search.cpan.org, but Kobesearch is quite nice as well now. Makeshifts last the longest.	[reply]
Re^3: An alternative Perldoc site by jj808 (Hermit) on Jan 21, 2005 at 14:24 UTC
The http://perldoc.perldrunks.org site is still quite heavily under development, so if could please be a bit more specific about what it is you don't like about the site then I'll certainly take your comments on board. Either post here or feel free to email me directly at jj@jonallen.info.	[reply]
Re^4: An alternative Perldoc site by Aristotle (Chancellor) on Jan 23, 2005 at 14:33 UTC
It's not interlinked. F.ex, look at the perl POD page on perldoc.com: each POD page name it mentions is hyperlinked. Your version of perl has no links. Same goes for the “See also“ section of the POD pages on your site. Check the rendition of perlfunc on perldoc.com: the functions are all linked. Then click its link for unpack and compare with your version of the unpack documentation: on perldoc.com, the link actually leads to pack, on your site, it does nothing. That forces the user to constantly back out of his reading and delve into the navigation to locate where it is what they wanted to read, before being able to continue. I realize providing such extensive linking requires non-trivial guessing in the general case and even special case guessing for some particular POD pages. I did write a POD-tree-to-HTML-tree converter myself, so I know it can be a pretty ugly job. But not doing that greatly diminishes the value of the resulting docs, at least as far as I'm concerned. Makeshifts last the longest.	[reply]
Re^5: An alternative Perldoc site by jj808 (Hermit) on Mar 02, 2005 at 22:11 UTC
Re^6: An alternative Perldoc site by Aristotle (Chancellor) on Mar 03, 2005 at 06:33 UTC
Re^5: An alternative Perldoc site by jj808 (Hermit) on Jan 23, 2005 at 22:22 UTC
Re^2: An alternative Perldoc site by Ytrew (Pilgrim) on Jan 22, 2005 at 06:45 UTC
Please, someone, explain to me this "offbox, gotta be on the web" obsession with documentation? For me, it's simple. I usually use the documentation that's sitting right on my computer. But sometimes, I need more. I only keep documentation for the version(s) of Perl that I'm running. It's occasionally quite useful to check the online docs for a different version, and compare feature sets. If I find a bug in my version of Perl, switching versions may solve my problem. If a feature was changed in a given release, my code may need to change slightly as well. Good documentation can help in both cases. Online documentation sites provide this information in an easy-to-browse format, for which I'm quite grateful. Downloading a full perl installation just to read documentation is a waste of time and bandwidth. -- Ytrew Q. Uiop	[reply]
Re^2: An alternative Perldoc site by Mutant (Priest) on Jan 21, 2005 at 13:14 UTC
I had never heard of tkpod - thanks for the tip. I think the main reason people rely on these sites is that they don't know about perldoc (or at least how to use it properly). And even if they do, they're like me, and prefer the 'pointy-clicky' interface (but don't know about tkpod).	[reply]
Re^2: An alternative Perldoc site by naChoZ (Curate) on Jan 21, 2005 at 14:19 UTC
I second the tkpod mention. Pointy-clicky is nice, but it's more that I like to leave it open in a small window beside my editor. But the really nifty thing worth mentioning is that it can use the perlindex cpan distribution to create an extremely convenient interface to search all the perldoc you've got. -- "This alcoholism thing, I think it's just clever propaganda produced by people who want you to buy more bottled water." -- pedestrianwolf	[reply]
Re^2: An alternative Perldoc site by bart (Canon) on Jan 22, 2005 at 23:47 UTC
The reason why I am glad about them, is so that I can use it as something to point people to. Perlmonks is a web-based medium, you can't just say "use `perldoc blah` to read the docs", I prefer real web links pointing directly into the docs you are currently talking about. The finer I can pinpoint the relevant section, the better, for example, I wish Quote and Quote-like Operators in perlop had subanchors, as for now, it's a bit of a largish block. It's also nice to have something to point to, in e-mail for example, to people who normally aren't Perl users, and thus, don't have perl installed.	[reply]
Re^3: An alternative Perldoc site by merlyn (Sage) on Jan 23, 2005 at 16:15 UTC
you can't just say "use perldoc blah to read the docs" Sure you can. I say it all the time here. I expect Perl users to be adult enough to translate that instruction into whatever's appropiate on their box. -- Randal L. Schwartz, Perl hacker Be sure to read my standard disclaimer if this is a reply.	[reply]
Re^2: An alternative Perldoc site by jacques (Priest) on Jan 21, 2005 at 18:04 UTC
Please, someone, explain to me this "offbox, gotta be on the web" obsession with documentation? IMO, Java and PHP are way ahead of Perl when it comes to online docs. This was brought up on use.perl not too long ago. Keep in mind that many programmers grew up on the web. These programmers expect online docs to be excellent.	[reply]
Re^2: An alternative Perldoc site by legato (Monk) on Jan 25, 2005 at 16:13 UTC
As a user of such sites, there is only one answer -- Windows. `man perldoc` is unavailable, and because the only Windows pager is a broken version of `more`, searching within the perldocs can be very annoying. I'm not allowed, at work, to install Cygwin or any kind of web server, so generating the HTML docs has met with limited success (`file://` sucks). So, when I need to search perl docs, I use an online repository. Them's the beans. As far as CPAN, I like being allowed to read docs before downloading the modules. The nice thing about the docs on perldrunks is that they can be downloaded for offline use as well. Anima Legato `.oO all things connect through the motion of the mind`	[reply]
Re^2: An alternative Perldoc site by Mr. Lee (Scribe) on Jan 22, 2005 at 22:20 UTC
because when you often work on different computer, then you don't have all your documentary on every computer, or box, you are using. In the office, you have mostly all the time dsl internet, and many doc sites already in the companys proxy cache anyway. Sadly, I might have to switch to php totally. If they does not change.	[reply]
Re^2: An alternative Perldoc site by Qiang (Friar) on Feb 01, 2005 at 23:32 UTC
I personally use perldoc. but to my other friends who are only use perl for web programming, they prefer accessing the document thr web. even to a newcomer, reading doc online is better than reading on the terminal. THAT is more user friendly. no wonder the way how php and mysql present their documentation is favored by most of the users. next time I will suggest perldoc and online doc at the same time.	[reply]