Re^2: I want site documentation updates and I want them now.

I've always found it very useful and handy to be able to refer to print in a normal sentence, whithout having to think about linking too consciously. Just like how people sometimes use "()", like in int() to indicate something is a function, it is handy on Perl monks to do so with "[]", like in [int], and have it link to the documentatin. The power of usability in these links is the lack of schema. (And the high threshold in using Perl Monks's schema links is made even higher by the mandatory "//" after the colon.)

Even if just a stub page linking to the perldoc.perl.org, perldoc pages here would be a good idea. It's laudable that you don't want to break old links (though in that respect, changing titles of 2 year old nodes certainly doesn't help much), but I think there should also be a focus on the future. This focus should not just be pure, it should also dwim. (I'm referring to Perl versus other languages. I think it's dwimmy to say [perlop], and needlessly (unperlishly) verbose to say [doc://perlop].)

Perldocs are very well defined, and only very few are added. When one is added, the stub can be introduced by any user. I volunteer for updating perlcheat to point to the actual up-to-date document on perldoc.perl.org; In fact, I'll do so right away. :)

There are two things regarding perldocs on Perl Monks that "seemed like a good idea [at the time]", namely mirroring documents here, and having short intuitive dwimmy links. One of them still is.

As for updating old nodes, you're kidding, right?

Juerd # { site => 'juerd.nl', do_not_use => 'spamtrap', perl6_server => 'feather' }

Comment on Re^2: I want site documentation updates and I want them now. Select or Download Code

Replies are listed 'Best First'.
Re^3: I want site documentation updates and I want them now. by GrandFather (Saint) on Dec 11, 2006 at 22:40 UTC
Why should perldoc links enjoy special status? I much more often link to module documentation so that is what should have special status isn't it? Actually it looks like a little code could disambiguate between these two cases. But how many other contenders for special link status are there? DWIM is fine where there is a clear "best guess" at the intended behaviour, but quickly becomes nasty when too much second guessing is involved. In this case I think typing 6 extra characters for most links is a very minor burden compared with an extra iteration or two of the preview/edit cycle when links don't DWIM. DWIM is Perl's answer to Gödel	[reply]
Re^4: I want site documentation updates and I want them now. by Juerd (Abbot) on Dec 11, 2006 at 22:45 UTC
Why should perldoc links enjoy special status? I much more often link to module documentation so that is what should have special status isn't it? Module namespace is in flux, while the perldoc list remains mostly static. This makes schemaless use very hard. I agree that it would be very nice to have easier links. Perhaps `[[foo]]` would be a solution, where this always links to documentation. perldoc.perl.org if the document is known to exist there, search.cpan.org/perldoc?foo otherwise. http://tnx.nl/foo already implements something like that. DWIM is fine where there is a clear "best guess" at the intended behaviour, but quickly becomes nasty when too much second guessing is involved. "perlop" and friends can be guessed with certainty, so that's not a problem. In this case I think typing 6 extra characters for most links is a very minor burden It's not that 6 characters by itself is a lot of work. It's that it changes the way one edits the line, which is especially relevant in the chatterbox, but no less important in normal writeups. The schema moves the link out of the realm of punctuation, into something that requires a conscious decision. Juerd # { site => 'juerd.nl', do_not_use => 'spamtrap', perl6_server => 'feather' }	[reply] [d/l]
Re^3: I want site documentation updates and I want them now. by jdporter (Paladin) on Dec 11, 2006 at 19:55 UTC
The power of usability in these links is the lack of schema. What you're saying, in a nutshell, is that the perl man pages should enjoy a special status that no other objects in the schema-less namespace do. I for one think that is inappropriate, not to mention unnecessary. People can toss out a `[print]` in the chatterbox, for ease of typing. If it happens not to resolve cleanly, it's no big deal. But when typing up a nice long meditation into which one has (presumably) already put significant minutes if not hours of thought, one can reasonably be expected to take the time to spell `[doc://print]`, just as one can reasonably be expected to write `[acronym://TIMTOWTDI]`, `[jargon://lart]`, `[mod://File::Find]`, or `[google://lwall-quotes]`. There's a limit to how much work we should expect the PerlMonks engine to compensate for our laziness, and I believe your proposal rather exceeds it. Even if just a stub page linking to the perldoc.perl.org, perldoc pages here would be a good idea. I'm not sure if you've visited the Library lately, but it, and all of our on-site perl docs, do in fact link to perldoc.perl.org. As for keeping our copies of the perl docs current — Not only does it not make sense to duplicate (crappily) what the folks at perldoc.perl.org are doing, the site maintenance crew don't have the resources to put into it. I think it's dwimmy to say `[perlop]`, and needlessly (unperlishly) verbose to say `[doc://perlop]`. Perhaps, but this is more about HTML than Perl. Be glad you don't have to write `<a href="http://perldoc.perl.org/perlop.html">perlop</a>`. We're building the house of the future together.	[reply] [d/l] [select]
Re^4: I want site documentation updates and I want them now. by demerphq (Chancellor) on Dec 15, 2006 at 11:39 UTC
Hrm, maybe some way to handle `[{printf}]` or `[&printf]` as a special case... --- $world=~s/war/peace/g	[reply] [d/l] [select]
Re^4: I want site documentation updates and I want them now. by Juerd (Abbot) on Dec 11, 2006 at 22:10 UTC
What you're saying, in a nutshell, is that the perl man pages should enjoy a special status that no other objects in the schema-less namespace do. I for one think that is inappropriate, not to mention unnecessary. Not just man pages, also most `=item`s from perlfunc. I for one think that is inappropriate, not to mention unnecessary. Convenience is never necessary. It is, however, convenient. People can toss out a print in the chatterbox, for ease of typing. If it happens not to resolve cleanly, it's no big deal. But when typing up a nice long meditation into which one has (presumably) already put significant minutes if not hours of thought, one can reasonably be expected to take the time to spell print, just as one can reasonably be expected to write TIMTOWTDI, lart, File::Find, or lwall-quotes. I'd almost guess that you use Perl only for one liners, and switch to a more verbose language (Java?) for larger projects. It's silly to assume that all people who already spent this much time on thinking, like to spend even more time on formatting their document. Links are so incredibly ubiquitous, and used inline, that the most convenient method of using them should be preferred at all times. That's why we have the square brackets in the first place. Links to perldocs and functions are (ought to be) placed much more often than links to normal nodes. They deserve a special status. There's a limit to how much work we should expect the PerlMonks engine to compensate for our laziness, and I believe your proposal rather exceeds it. Perl Monks engine? Huh, I never implied such a thing. For all I care, a normal user just writes up some meditations (or whichever node type) that link to the respective actual documents. This can be automated. I volunteer. Doing this once will eventually save me time, even if nobody else uses it, and even though I don't use this site that much anymore (partly exactly because of the way things are done here, and this is a good example). If only because then all the old links start making sense again, which was the point of the root of this thread. (Gawd, I find it hard to believe that 4 years later, this (to me rather trivial) issue still exists.) Don't be afraid to learn from the wiki work flow, which is to make linking incredibly easy. So easy that you can do it while typing, instead of as an afterthought. I'm not sure if you've visited the Library lately, but it, and all of our on-site perl docs, do in fact link to perldoc.perl.org. As for keeping our copies of the perl docs current — Not only does it not make sense to duplicate (crappily) what the folks at perldoc.perl.org are doing, the site maintenance crew don't have the resources to put into it. This site doesn't need copies. Even in 2002, when I posted the OP of this thread, I already said that links would suffice. And maintaining that can't be hard. All it needs is some new nodes for new documents, like uniintro, and perlcheat. Perhaps, but this is more about HTML than Perl. Be glad you don't have to write perlop. I'm speechless.	[reply]
Re^5: I want site documentation updates and I want them now. by jdporter (Paladin) on Dec 11, 2006 at 23:00 UTC
Convenience is never necessary. It is, however, convenient. Editor macros are great tools for convenience. [a] user just writes up some meditations ... that link to the respective actual documents. ... then all the old links start making sense again So, the continuation of this debate is just a part of the "single-word title" flamefest, raging in another thread somewhere. We're building the house of the future together.	[reply]
Re^6: I want site documentation updates and I want them now. by Juerd (Abbot) on Dec 12, 2006 at 00:14 UTC