|
Re: An alternative Perldoc site
by merlyn (Sage) on Jan 21, 2005 at 12:56 UTC
|
I am continually puzzled as to why people want to go off their own box to look for docs elsewhere, when in fact everything that they need is right at their fingertips. Why is this?
I mean, I type "man" (well, I have GNU emacs do that for me behind the scenes). I type "perldoc -t". I can even use tkpod if I really want a pointy-clicky-hyperlinked docset. And all of those don't require an internet connection, and are much faster than going somewhere else.
And, they refer to the precise version I have installed, not whatever version happens to be at a public website.
Please, someone, explain to me this "offbox, gotta be on the web" obsession with documentation?
| [reply] |
|
|
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] |
|
|
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] |
|
|
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] |
|
|
| [reply] |
|
|
|
|
|
|
|
|
|
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.
| [reply] |
|
|
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] |
|
|
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] |
|
|
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] |
|
|
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] |
|
|
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.
| [reply] |
|
|
| [reply] |
|
|
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] |
|
|
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] |
|
|
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] |
Re: An alternative Perldoc site
by fireartist (Chaplain) on Jan 21, 2005 at 09:17 UTC
|
| [reply] |
|
|
| [reply] |
|
|
| [reply] |
