Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

I want site documentation updates and I want them now.

by Juerd (Abbot)
on Jun 02, 2002 at 13:35 UTC ( [id://171024]=monkdiscuss: print w/replies, xml ) Need Help??

As we all know, this site holds old 5.0 perldocs. Perldocs on this site are handier than linking directly to perldoc with the perldoc:// tag, because that is a lot of typing.

After some ranting about this, crazyinsomniac told me that there has been discussion and the decision was that this site would never get a documentation update. That's a shame.

If it is not going to be updated, it needs to be removed. We are now giving people bad advice by refering them to old documentation. That is not a nice thing to do.

I suggest that we remove all documentation and link to http://perldoc.com/ instead. While you're at it, add documentation for all releases. I'm thinking of something like this:

perlreftut

Perl documentation is no longer maintained on this site. Please refer to one of the documents below:

It shouldn't be hard to implement.

We're Perl Hackers. We can parse html, we know how to link. There is, in my view, no excuse to not do this. I have no idea how Everything works, but I'm sure the possibility of updating nodes automatically does exist, somehow.

crazyinsomniac said I had to have convincing code to support my plead. I don't know if the following is convincing, but it should ease the automatic node updates:

use HTML::TreeBuilder; use LWP::Simple; use Data::Dumper; print Dumper( do { my %pod; push @{ $pod{ substr $_->[1], 4, -5 } }, "http://perldoc.com/perl$ +_->[0]/$_->[1]" for map { my $v = $_; map { [ $v, $_->attr('href') ], } HTML::TreeBuilder -> new -> parse( get "http://perldoc.com/perl$v/pod.html" ) -> look_down( _tag => 'a', sub { shift->attr('href') =~ /^pod/ } ) } reverse sort map { $_->attr('value') } HTML::TreeBuilder -> new -> parse( get 'http://perldoc.com/' ) -> look_down( name => 'version' ) -> content_list; \%pod; } );

Please make this site a bit more useable.

- Yes, I reinvent wheels.
- Spam: Visit eurotraQ.

Replies are listed 'Best First'.
Re: I want site documentation updates and I want them now.
by webfiend (Vicar) on Jun 02, 2002 at 20:00 UTC

    You mean I've been studying old docs when I bounce through the reference section? Aww, maan... ;-)

    I definitely agree that Perlmonks should have no reference section rather than something that is badly out of date. On the other hand, if it's easier to leave it in rather than remove or update it, I guess I can understand the reluctance to do anything.

    ... I think I'm getting really good at this "ambivalence" thing...


    "All you need is ignorance and confidence; then success is sure."-- Mark Twain
Re: I want site documentation updates and I want them now.
by atcroft (Abbot) on Jun 02, 2002 at 21:07 UTC

    Excuse a simplistic question, because I am not familiar with the internal workings of the engine behind the site, but would it not be possible to make the links in the Library or using the perldoc tag to link to the docs on the perldoc.com site, and translate those links that would be to pages in there into links to that site as well? Perhaps even on the library page have a set of links near the top for the version you desired, so if you clicked that the links presented went to that version's pages there?

    If I am naive, please forgive and illuminate my way from ignorance.

Re: I want site documentation updates and I want them now.
by greenFox (Vicar) on Jun 03, 2002 at 00:52 UTC

    My more cynical side thinks that this won't be a priority until the SOPW etc. start getting hit with questions along the lines of "Help! I followed the docs and my code still doesn't work" :-) -my more cynical side also responds to this with "as if!" :)

    I agree though, sooner or later updating the docs in some way will become imperative, whether with the introduction of perl 6 or before. If an automated update of the existing docs is not feasible then I think replacing them with links to perldocs is the solution, a monastery without a library would be unthinkable!

    --
    my $chainsaw = 'Perl';

      until the SOPW etc. start getting hit with questions along the lines of "Help! I followed the docs and my code still doesn't work" :-)

      That is already the case :)

      a monastery without a library would be unthinkable!

      Monasteries in general have old books. We should know better :)

      - Yes, I reinvent wheels.
      - Spam: Visit eurotraQ.
      

      Heh, perl 6 looks like it's making JUST enough changes that that might start happening when they release it.



      "Weird things happen, get used to it."

      Flame ~ Lead Programmer: GMS

(tye)Re: I want site documentation updates and I want them now.
by tye (Sage) on Jun 05, 2002 at 20:15 UTC

    I'll reply to lots of nodes from this thread in one place.

    Yes, kudra, something was done. I just finished and went to review the thread before posting the summary and find wonderings already. (:

    Yes, a patch was proposed to try to address this. It turned out to be more like Perl pseudo code than a final solution, but after wrangling for a while with the many possible ways to address this, the basic idea in the patch was chosen as a good one. I reworked the patch and made two other versions of it to cover the 3 node types that encompass most of the local documentation that is better maintained at perldoc.

    Note that there will be some invalid links due to differences in versions of the documentation, etc. as well as new docs that don't have nodes. And someone will have to update the perldoc version number lists from time to time. There are also a few nodes that should be covered by these changes but aren't. And we should some day add the perldocver setting to user settings so you can select which version the first link takes you to (and then perhaps use that setting for other purposes as well).

    For future reference, if you want a response from one of the gods, then I suggest you avoid "and I want them now" (which immediately had me thinking "Tough beans. That issue is trivia compared to some of the things on my list. With that attitude, you'll just have to wait.") and that you don't complain if it takes a few days.

    It took several days just to get a good handle on the details of the problem and the consequences of the several possible work-arounds. No, I didn't post a node saying "I've read this. I'm thinking about it. I'll get back to you." (Heck, just reading it wasn't at the top of my list after I read the title.)

    Several people have said that they'll write something to update the local documentation. If one of them eventually delivers, then we'll reword the disclaimer but leave the links up.

            - tye (but my friends call me "Tye")

      I figured I should make a post on this, so people can ++ me for that patch. (What, me, an XP whore? Never.)

      It wasn't purticularly meant to be psudocode, but that's OK. I like your version better. Also, I rather forgot that perlfaqs were sepperate nodetypes. (Or didn't know.) And I was assuming that the same script would be made the displaytype for both/all three nodetypes, rather then three seperate scripts.

      For my first everything superdoc writing, I think it wasn't that bad.

      I would have prefered to write somthing to update the local docs, rather then (or even better, as well as) pointing at perldoc, but I didn't (and don't) know enough about Everything.

      And it would be nice to hear more often what the Gods have in mind for the site.


      We are using here a powerful strategy of synthesis: wishful thinking. -- The Wizard Book

(Us and Them) Re: I want site documentation updates and I want them now.
by talexb (Chancellor) on Jun 03, 2002 at 13:30 UTC
    I think this is an important issue -- Perl is complicated enough already without throwing in "Oh wait, what version are you using?" questions at new monks.

    I started with Perl 5 (just as it was released, I think) in the summer of '98. The migration to 5.6 was relatively painless -- a new version of Programming Perl (2nd edition -> 3rd edition) was about the only change. Going to version 5.8 is going to take a little effort, and Perl 6.0 is going to require some major thought changes (not unlike Perl 4 -> 5).

    Let's avoid a Tower of Babel situation -- there needs to be some version identification tied with the documentation on-site, along with links to where the newer stuff is. So currently the site documentation would be labelled as Perl 5.0 -- we need to have links to 5.6 docs (the current version) as well as 5.8 docs (the upgrade version currently under development) and eventually 6.0 docs (the really cooll new version that Damian Conway (among others) has been talking about for a year).

    --t. alex

    "Nyahhh (munch, munch) What's up, Doc?" --Bugs Bunny

(crazyinsomniac: nudge) Re: I want site documentation updates and I want them now.
by crazyinsomniac (Prior) on Jun 05, 2002 at 18:42 UTC

      I hope you'll become a pmdev soon.

      /me too is restricted in time. Becoming a pmdev would mean learning how Everything works, and communicating a lot. I can find some time to write nodes, but that's about all I can do. I hope one of the current pmdevs can find some time to implement this. The code I wrote for this uses a very general data type so that it can be implemented in virtually anything Perl.

      { document => [ urls sorted by release (newest first) ], ... }

      - Yes, I reinvent wheels.
      - Spam: Visit eurotraQ.
      

Re: I want site documentation updates and I want them now.
by Aristotle (Chancellor) on Jun 02, 2002 at 14:57 UTC
    Sorry, I can't ++ this more than once. :-)

    Makeshifts last the longest.

Re: I want site documentation updates and I want them now.
by cybear (Monk) on Jun 03, 2002 at 11:46 UTC
    Please consider...

    Some of us are cursed with companies that have only recently discovered the wheel. hahaha Keeping the old but adding the new would be, by far, the best alternative.

    1). We need the old documentation. Getting up to Perl 6 is several years away from common acceptance, for the multi-national that I work for. I'm sure that many others are in the same circumstance.

    2.) If the old documentation were to go away then reverse engineering the scripting that previous, and inferior, hackers have... hacked together will become more difficult.

    3.) Transitioning scripting from Perl 5 to Perl 6 will require access to Perl 5 documentation.

    4.) How can you appreciate the niffty new keen cool updates in Perl 6 without an appreciation for Perl 5?

    5.) etc, etc, etc.

      Keeping the old but adding the new would be, by far, the best alternative.

      You did not read my post. I suggested adding links for all releases that have documentation on perldoc. The oldest is 5.004, the newest is currently 5.7.3, but I expect it to be 5.8.0 soon.

      Getting up to Perl 6 is several years away from common acceptance, for the multi-national that I work for.

      That is great! Maybe it will be accepted as soon as it's released, which would be wonderful! For your information: Perl 6 hasn't even been designed completely yet.

      Transitioning scripting from Perl 5 to Perl 6 will require access to Perl 5 documentation.

      Just as a side note: all documentation is distributed with perl itself, so you probably have the documentation right there on your hard drive. Besides, perldoc.com will hold old releases for a long time.

      5.) etc, etc, etc.

      Please do tell, as your 4 other points weren't too useful.

      - Yes, I reinvent wheels.
      - Spam: Visit eurotraQ.
      

        Actually 5.7.3 is dead. Its 5.8 now (rc1). The change happened on the 29th.

        Just being pedantic. But I completely agree with you the documentation should either be upgraded or it should go completely, to be replaced by perldoc.com

        Thanks for writing this. ++

        Yves / DeMerphq
        ---
        Writing a good benchmark isnt as easy as it might look.

Re: I want site documentation updates and I want them now.
by jdporter (Paladin) on Dec 11, 2006 at 16:06 UTC

    I know the parent node is quite old, but I feel it's worth pointing out that the situation with the on-site Perl docs has changed and solidified significantly in the intervening years.

    1. The Perl docs hosted at PerlMonks are frozen and deprecated. (And that's final. Until further notice.) It may have seemed like a good idea in the days before perldoc.perl.org, but if we tried to maintain the Perl docs here, it would not only be redundant but couldn't be done nearly as well.
    2. Old-style links to the on-site Perl docs (e.g. [perlman:perlfaq1]) are therefore discouraged, though support for them, such as it is, will continue indefinitely for the sake of existing nodes which use them.
    3. New code should use the doc:// shortcut type to link to any page of the Perl docs. Authors are encouraged to update their old nodes with this syntax as well. The current PerlMonks site documents have been updated to use only this form. Note that the Function Nodelet now links directly to perldoc.perl.org as well.
    We're building the house of the future together.
      For most tokens I am content with [doc://] and [mod://], but once in awhile I find a keyword that doesn't work.

      You can link to map and grep, but not for or foreach. For those you need something like this: [doc://perlsyn#Foreach-Loops-for-foreach|foreach] (foreach)

      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' }

        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
        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.
Re: I want site documentation updates and I want them now.
by Juerd (Abbot) on Jun 05, 2002 at 18:33 UTC

    There is, in my view, no excuse to not do this

    Except for not having the time, of course. Sorry 'bout that.

    - Yes, I reinvent wheels.
    - Spam: Visit eurotraQ.
    

Ugly, ugly FAQ
by chicks (Scribe) on Jun 02, 2002 at 19:39 UTC
      It does? Are you using the latest Mozilla (RC3)? It looks fine here.

      -sam

      This ("Ugly Ugly FAQ") belongs in it's own thread, and is rather off topic...



      "Weird things happen, get used to it."

      Flame ~ Lead Programmer: GMS

gods? pmdev?(Re: I want site documentation updates and I want them now.)
by Juerd (Abbot) on Jun 05, 2002 at 14:20 UTC

    I wonder how long it will take for one of the ones who can actually implement the change to respond. When I wrote the node, I thought that wouldn't take long, but it has already been three days now.

    Please respond. Please don't make me think you're ignoring user input.

    Update: This was wrong. I should not have posted this reply - at least not this fast. My view of time is wrong: three days is not long at all. I'd like to thank everyone who has replied, especially the ones who have made the changes.

    - Yes, I reinvent wheels.
    - Spam: Visit eurotraQ.
    

      I think it's something worthwhile to consider/address. However I don't have the time/motivation at the moment. If you wanna join pmdev and do the work yourself by all means feel free.

      Recognize that all the people in pmdev and gods are volunteers. I know personally I respond much better to requests, or "Wouldn't it be cool ifs" than things that sound like demands. That being said I don't personally have a lot of time or motivation to devote to such an endeavor at the moment, maybe someone else will step up to the plate.

        Recognize that all the people in pmdev and gods are volunteers.

        I do, and I respect their efforts to make things better. However, I do find it a bit odd that none of the people who have the power to implement replied (well, you did now (and thank you for that)).

        I know personally I respond much better to requests, or "Wouldn't it be cool ifs" than things that sound like demands.

        The title is provoking to draw attention to the issue. This is not a new problem, and there has been discussion about it before. When you strip Dumper() off the given code, you get a hash reference that I'm sure can be turned into something useful for the database. This doesn't fix the individual perlfunc =items or the ones from perlfaq, but there haven't been that much changes in those (afaik).

        If my request sounds like a demand (which I can imagine with this title), please excuse me.

        maybe someone else will step up to the plate.

        I surely hope so! (And many others do too)

        - Yes, I reinvent wheels.
        - Spam: Visit eurotraQ.
        

      Something appears to have been done: a quick look at the documentation shows a note that it is out dated, along with a link to perldoc.com.

      On one hand I would like to see more responses from gods on issues like this. It is rather frustrating that there isn't a great deal of communication about future plans and the direction of site development. For example, it was roughly three weeks after the site switched to CSS that I learned there were plans to eventually fix things for those of us whose CSS implementations are linked to JavaScript.

      On the other hand, I don't think three days is a long time. The News section was offline without comment for something like six months--that's a long time. Also, there are plenty of pressing concerns, and I wouldn't be surprised if documentation ranks pretty low compared to issues like server overloading. Don't forget there are also a lot of suggestions made and it would probably be a full-time job to respond to them. Making demands probably won't increase responsiveness. Update: I hadn't read vroom's post before writing this. Just refer to the points he made for a summary of what I wanted to say with this paragraph.

      So what can be done? I would like to see a member of gods post a (weekly?) status report just to give the rest of us a general rundown of developments. They could take turns, or it could be a god-writeable everyone-readable wiki where a brief note could be added when decisions are made. These ideas, however, do require members of gods to make communication a priority.

      Any individual who wants to hear about site changes would probably do better to hang out on IRC and listen to the discussions. An enterprising person might post summaries of these discussions (with permission, of course), which would solve the lack of communication without putting any more pressure on the developers. No doubt there's a good deal of xp in it as well.

        So what can be done?
        ... it could be a god-writeable everyone-readable wiki where a brief note could be added when decisions are made.

        To wrap up this particular sub-thread: there is now the Tidings wiki (aka "What's New at PerlMonks" in your Information nodelet), updated by members of the Cabal as user-visible changes to the site are made.

        We're building the house of the future together.
      Gods don't/can't read all of the nodes that come out. I believe the process to have something changed would be done at the node Make your petition. It'd also probably be a good idea to include a link your node to so whoever is deciding/thinking can see what everyone is thinking.
      Good luck.

        Gods don't/can't read all of the nodes that come out.

        I think a node with a reputation of > 150 stands out on its own, but I'll add a petition anyway. Thank you.

        Update The "make a petition" link just posts to Perl Monks Discussion, the very category this thread is in. The petition adding page does not state that. I assume you didn't know.

        - Yes, I reinvent wheels.
        - Spam: Visit eurotraQ.
        

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: monkdiscuss [id://171024]
Approved by ariels
Front-paged by ariels
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others having an uproarious good time at the Monastery: (5)
As of 2024-03-28 14:30 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found