http://www.perlmonks.org?node_id=281219

sri has asked for the wisdom of the Perl Monks concerning the following question:

Hi Monks,

Lately I've been playing around with POE and i think it's really great.

But it's really disappointing that there is not much documentation nor examples out there.

Also it seems that there are not much projects using it.

I know of the POE Cookbook and projects use POE but both seem very out of date.

This is very complete, but hard to understand, when you never used POE before.

Is there something better out there that I've missed?

Replies are listed 'Best First'.
Re: Documentation for POE?
by JamesNC (Chaplain) on Aug 06, 2003 at 02:21 UTC
    Here is my favorite POE Tutorial: Matt Sergeant's POE Tutorial is a pretty good one I think ( and kind of humorous :0) Once you get the knack of what's going on you really start to appreciate POE. Rocco Caputo told me that he knows of 2 folks working on POE books, but he didn't know when they would be available for public consumption. He said he is too busy to write one. I think a tutorial on this site would be fitting.
    I have a simple example of a POE SSL Client with a Tk interface on this node (POE SSL Tk) It showes you how POE can be used in a non-blocking SSL Client that polls 2 https web pages cooperatively.

    JamesNC
[reply]
[reply]
Re: Documentation for POE?
by Mr_Person (Hermit) on Aug 06, 2003 at 02:43 UTC

    You might find the Beginner's Introduction to POE over at perl.com useful.

    For me the best way to learn more about POE was to just start using it. In many ways it's very different from other styles of programming and can take a while to get used to. But once you get the hang of it you'll never look back! I also found the POD included in the modules to be fairly well written and just taking the time to sit down and read through it helped a lot.

[reply]
Re: Documentation for POE?
by Azhrarn (Friar) on Aug 06, 2003 at 05:14 UTC
    Documentation has been an admitted problem, and they are trying to form a scheme to keep things coherent. There is a ton of documentation in the fairly dense POE modules themselves, and Dngor is working on consolidating it into more readable forms.

    Good places to start:
    Beginners Guide
    Dennis Taylor's Introductory Article (Raw POD, but I found it a good read) (EDIT: Woops, seems to be the same article as Mr Person's perl.com link. :) - Not sure if there are revisions in the POD or not)
    POE FAQ
    POE Cookbook
    Evolution of a POE Server (A GREAT guided tour through designing a POE application from the ground up)

    Out of the Main POE docs, POE::Session is probably the most important to understand, closely followed by POE::Kernel. As you can get by with just understanding the constants the Kernel exports at first.

    I've read through the majority of the POE docs many many times over the past few months as I dabble in various projects, and still keep coming across more little things. Also, don't be afraid to just make your own page on the wiki and post questions there, or even on an existing page like the FAQ. It lets the friendly devs over there know what parts confuse people the most, and someone usually sees your question fairly quickly and will be happy to help you understand it.

[reply]
      Trouble is, having a ton of documentation is not really useful if there's not enough introductory stuff. POE suffers from this. The way people use documentation, at least when starting out, is they want to ask "I have problem X, how do I solve it". The POE docs don't help here, they're just a reference - at least that was the case last time I looked. But a reference is only useful once you know what you're doing.

      Last time I whined about this, Rocco said that he knew it was a problem and he'd be happy to accept any documentation I could write. Unfortunately there's a bootstrapping problem there - without having sufficient documentation I couldn't learn the product in any reasonable time scale and so couldn't write the documentation.

      exim suffers from the same problem. I learnt exim not from the docs but by taking someone elses config file and hacking it until it Did The Right Thing. I tried to learn POE the same way - taking the test suite and trying to turn it into my application, but POE's just a wee bit too complicated for me to learn it that way ;-)

[reply]
Re: Documentation for POE?
by l2kashe (Deacon) on Aug 06, 2003 at 01:00 UTC

    For me the cookbook was enough. I was out looking for a MUD to hack away on, and found one in Perl. Well it used this module POE, that I hadn't used before. Between code in the MUD (which just plain didn't work, but got the point across) and the cookbook, it was enough to get moving. What really sent it home was using the chat server example to start in on my own MUD.

    So what I'm saying is that I haven't found any documentation that is a gentle introduction to POE ala the Llama book. I have found that the documentation is excellent once you understand how POE is put together and why things work the way they do.

    There was another thread not too long where I stated I was interested in starting a POE Tutorial here at the monastary. I still am, but have been too busy hacking away on the MUD to get rolling on it. I guess I wouldn't mind maybe sharing email addresses with some other monks if they are interested in starting in on it with me, and that will provide just enough motivation to get rolling ;) /msg me if anyone is interested

    use perl;

[reply]
Re: Documentation for POE?
by rcaputo (Chaplain) on Aug 07, 2003 at 09:03 UTC

    I am POE's lead developer, lead documenter, and lead site designer. I'm also the lead support agent, head fluffer, and chief bottle washer. I do all these things and more, even Europa, because nobody else does. If you would like to share or wear one of these hats, send me a note.

    Thank you all for the feedback. POE is free software, and I spend most of my free time working on it. As such, I don't have much time to read PerlMonks. I wouldn't have even looked at this node if someone hadn't pointed it out to me.

    If you're serious about making a difference in the project, please consider posting your feedback somewhere more useful. That would be my inbox, or POE's mailing list, or even a small note on the wiki itself.

    If you're just looking for a place to vent ineffectually, I suggest SlashDot instead of PerlMonks. They really get off on plagiarized Roger Ebert reviews.

    While I'm here:

    POE's documentation is big. Really big. Like 120 printed pages for the perldoc alone. The web Cookbook is probably another 70 pages, and then there are the tutorials1,2,3,4, the FAQ, and other discussions. It's probably enough to make a book.

    Unfortunately it's not book-quality documentation. I'm rewriting it in my spare time, which is obviously not fast enough. If you'd like to help it be done sooner, let's talk.

    Hossman's right. The site is a wiki. It's easy to update. A lot of people do change it. Thank you, people! It's great stuff, especially since any time I'd have to manage the site would probably be better spent revising documentation.

    William G. Davis is only partly correct about global.css. It's not editable directly, but you can change the site's style sheet. The user preferences include a field where you can insert your own styles or link to an entire stylesheet. It's mentioned towards the bottom of the main page.

    DrHyde's impression of POE seems to be stale. A few years ago the test programs were all the samples it had. These days I wouldn't wish them on anybody.

    The Cookbook is the main repository for sample programs now. So far there are 45 complete, commented programs covering different tasks. Many of them were written on request, so request something if you'd like to see it there. Likewise, let me know if any are out of date---it happens. Better yet, do like others have done, and patch the code without bothering me. It is a wiki.

    Thanks again for the feedback, and thanks for reading.

    -- Rocco Caputo - rcaputo@pobox.com - poe.perl.org

[reply]
Re: Documentation for POE?
by Anonymous Monk on Aug 05, 2003 at 23:54 UTC
    The worst thing about POE is their website. It's very bland. Sometimes I feel like yelling when I think about how terrible Perl programmers can be when it comes to web design. I will not point anyone by name, but you know who you are! Just google for gogopuffs and you will see what I mean. Thankfully, after far too many years, perl.apache.org and perl.org have new looks. Gee, guys ya think that was a good idea? Many of the younger generation like thinking of their languages as stylish and Perl does not put forth such an image at all. Just look at java.com, java.net or even php.net. Now I know someone will call me a troll and say "Perl is about getting the job done, not style or image. Perl is not pretty, it just gets the job done . . . blah, blah". Well, you can get the job done AND look good too. Personally, and I know that this statement will seem imflamatory, I believe that Perl attracts a lot of system administrators and in my experience, there is no other group on the planet that is worse at web design than system admins. This is just my opinion. Please let's not argue.
[reply]

      I won't argue with you, but if you feel so strong about it then just edit the damn thing and make it look better.

      It is after all a publicly editable Wiki, so if you think it's ugly, make it pretty.

      (And then other people can complain about how it's got too much flash, and not enough substance, and I can chastise them for not adding content, and we'll get into a really nice positive feedback loop that will result in a constantly growing & sexy to look at site that will improve without bound for ever and ever....)

[reply]
        What a great design concept: Create an ugly site, but include a Wiki, so when people complain, you can tell them to fix it themselves. Brilliant.
[reply]
        Well, considering that the website looks to be dozens of pages in size and that the Wiki only gives you access to stuff between the opening and closing <body> tags, with each page using the same stylesheet that no one can change (global.css), I don't think it's reasonable to assume that anyone can just "edit it" and make it look "pretty."
[reply]
      Not to flame, but I thought the same when I saw this the first time. :)
[reply]
Re: Documentation for POE?
by Anonymous Monk on Aug 06, 2003 at 01:27 UTC
    POE is a big wad of potential waiting for your kinetic. It's a mirror reflecting your ideas in code. It's the dingdong in shamalamadingdong. It's the hoho in hohoho, and at least one Po in PoCo. It's the freak in fries. It's all these things and more, even Europa, and you can attempt a landing there.

    How could the documentation possible be better? ;-)

[reply]
Re: Documentation for POE?
by Petras (Friar) on Aug 06, 2003 at 14:57 UTC
    If you really want to know all there is about Poe, ask Ovid ;). If you don't know why that's funny, then you really should ask him!

    Cheers!
    Petras
    Don't worry about people stealing your ideas. If your ideas are any good, you'll have to ram them down people's throats.

    -Howard Aiken
[reply]
Re: Documentation for POE?
by princepawn (Parson) on Aug 06, 2003 at 16:34 UTC
    You might also look at Stem a system with similar functionality.

    Carter's compass: I know I'm on the right track when by deleting something, I'm adding functionality

[reply]

Back to Seekers of Perl Wisdom