What happened to the tutorials

[softweyr]

So the new API documentation is all lovely and apple-like, but what happened to all the helpful tutorials that used to be on the documentation site? We're supposed to go scrabbling around in the source directories, resorting to 'grep -r', to find the example code now? That's NOT an improvement.

[alex]

Did you check the Documentation front page?

[softweyr]

Yes, a few hundred times. Ages ago (2008-ish?) the documentation page used to link to these well-written tutorials on most of the top-level Poco libraries, with code from the sample programs interspersed. Now, we get slides, which are the WORST way of documenting or teach coding in the whole world. If the old pages are still available, I'd like to see them linked into the doco somewhere, so I can still point people at them.

If you don't know what I'm talking about, maybe a trip to the Internet Wayback machine is indicated.

[alex]

Write another rant like this one and you may be looking for your answers in the Wayback machine. We're getting tired of people like you demanding but never actually offering any help. Next time you get tempted to be smart, please remember that you get all these things you are ranting about for free and that gives you no right to demand anything from us, especially not in a sarcastic and disrespectful way.

[guenter]

Unfortunately, the old Wiki pages are no longer available, as I got tired of maintaining the Wiki, which at one point meant removing Wiki spam every day. YMMV, but IMO the slides provide much better material than the old tutorials which were very limited in their coverage. Also, I don't remeber them being that great anyway. Some of the better tutorials and manuals (Data, Zip) have been included in the reference documentation.

[softweyr]

Unfortunately, the old Wiki pages are no longer available, as I got tired of maintaining the Wiki, which at one point meant removing Wiki spam every day. YMMV, but IMO the slides provide much better material than the old tutorials which were very limited in their coverage. Also, I don't remeber them being that great anyway. Some of the better tutorials and manuals (Data, Zip) have been included in the reference documentation.

I poked through what the Wayback Machine had, and it's snapshots didn't go deep enough to find what I was looking for. See for instance http://web.archive.org/web/20071029124026/http://pocoproject.org/ which would have been about the time I was using Poco the last time around. I think it was the tutorials in the PDF docs that I'm recalling; the programs were small but were explained quite well by the surrounding text. (The date I left that job, Oct 22, 2007, stands out clearly in my mind because it's also the day my home was destroyed in a firestorm.)

I like the doxygen-generated reference site now, but it's quite hard to get an idea of how to pick particular DOM elements out of a document by looking at the class method descriptions for the Poco::XML or Poco::XML::Element classes. Somewhere, you need to refer to a program that actually instantiates a document object and uses these functions, and hopefully have some text explaining why you might want to do that.

I'm more than happy to post (most of) the source to the program I've just finished, along with commentary, if someone would find that useful. It's a couple hundred lines long and not hard to explain, and I'm happy to have knowledgeable Poco users poke fun at it too.

[alex]

Unfortunately, the old Wiki pages are no longer available, as I got tired of maintaining the Wiki, which at one point meant removing Wiki spam every day. YMMV, but IMO the slides provide much better material than the old tutorials which were very limited in their coverage. Also, I don't remeber them being that great anyway. Some of the better tutorials and manuals (Data, Zip) have been included in the reference documentation.

I agree. Additionally, some wiki tutorials (Data in particular) were referring to trunk code which was not released; this, in turn, was causing confusion with many users because code from tutorials was not available in releases. With that said, if someone would offer to actively maintain tutorials wiki, I'd have no problem with that.

[marlowabnp]

FWIW, I like the tutorial slideshows. However, I don't think they go far enough. I would like to see more on how to do socket programming with SSL. IMHO the material that deals with this is inadequate. I am struggling to figure out how to use this particular aspect of Poco.

[Royce]

I had to struggle a bit to get going with SSL as well.

For just getting OpenSSL compiled I was able to use this page: http://www.ski-epic.com/2007_notes_on_openssl/index.html
For getting my self signed cert for testing I used this page: http://www.madboa.com/geek/openssl/#cert-self
Code wise I overrode the initialize method of ServerApplication, got my configuration loaded that had my openSSL properties defined, called the base class method, and then called Poco::Net::initializeSSL(). (Similarly for uninitialize but in reverse)

My OpenSSL properties for the my self- signed cert looked like this:

Code: Select all

openSSL.server.privateKeyFile = ${application.configDir}mam.pem
openSSL.server.privateKeyPassphraseHandler.name = KeyFileHandler
openSSL.server.privateKeyPassphraseHandler.options.password = secret
openSSL.server.verificationMode = none
openSSL.server.verificationDepth = 9
openSSL.server.loadDefaultCAFile = true
openSSL.server.cipherList = ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
openSSL.server.privateKeyPassphraseHandler.name = KeyFileHandler
openSSL.server.privateKeyPassphraseHandler.options.password = secret
openSSL.server.invalidCertificateHandler.name = AcceptCertificateHandler
openSSL.server.extendedVerification = false
openSSL.server.cacheSessions = true
openSSL.server.sessionIdContext = ${application.name}
openSSL.server.sessionCacheSize = 100
openSSL.server.requireTLSv1 = false

openSSL.client.privateKeyFile = ${application.configDir}mam.pem
openSSL.client.privateKeyPassphraseHandler.name = KeyFileHandler
openSSL.client.privateKeyPassphraseHandler.options.password = secret
openSSL.client.verificationMode = none
openSSL.client.verificationDepth = 9
openSSL.client.loadDefaultCAFile = true
openSSL.client.cipherList = ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
openSSL.client.privateKeyPassphraseHandler.name = KeyFileHandler
openSSL.client.privateKeyPassphraseHandler.options.password = secret
openSSL.client.invalidCertificateHandler.name = AcceptCertificateHandler
openSSL.client.extendedVerification = false
openSSL.client.cacheSessions = true
openSSL.client.sessionIdContext = ${application.name}
openSSL.client.sessionCacheSize = 100
openSSL.client.requireTLSv1 = false

After that point I just had to use a SecureStreamSocket/SecureServerSocket where I was using just plain StreamSocket/ServerSocket. Later I was able to experiment with the property settings such as verification.