Yes, what ever attempts are made to improve the documentation, they should probably start with errors and omissions in this book, rather than from scratch.
Perhaps O'Rielly might want to publish a followup? -----Original Message----- From: owner-openssl-us...@openssl.org on behalf of Mark Sent: Fri 11/27/2009 2:46 AM To: openssl-users@openssl.org Subject: RE: General question about documentation Hi All, > Rene Hollan wrote: > > > > Oh, you need to dig deeper, to understand the semantics and > not just > > the syntax of those APIs. > > > > I didn't say using the source as documentation was > convenient, but it > > is possible, to any degree of detail you want. > > > > To wit: given the source code, it is possible to create > documentation > > to any degree of convenience. But, given some instance of external > > documentation and no source, it is not possible to improve the > > convenience factor of that documentation to an arbitrary degree. > > > > Suggesting what people who donate their time DO is rather > like herding > > cats. Some like coding and others like documenting and some > like both. > > Perhaps instead of an admonition that the project needs better > > documentation, a question regarding who is willing to contribute to > > said better documentation is more in order. > > > > unluckily, those of us who most need the docs are least able to > contribute, as I haven't the foggiest notion how to properly > use any of > the APIs at present. I suppose I need to get the ORA book and start > reading, as eventually I"m going to be helping another > development team > at work with getting an SSL connection going that needs to > use a client > certificate stored on a PKCS#11 PKI token, so I'll be sorting > out how to > use libssl w/ opensc's engine-pkcs11 module, who's > documentation is just > about as non-existant as that of openssl. this task was very easy in > Java, as Java's SecureSocket hides all the complexity, up to and > including full support for PKCS#11 plugins. The O'Reilly book is essential reading IMHO but it is far from a complete guide to OpenSSL. There are many APIs that it does not mention at all. It is also quite old now (2002). I realize that in Open source projects it is hard to find the time to document the software but I believe that documentation is an essential part of any project, especially something as complex as OpenSSL. Even if a wiki turnout out to be a better FAQ then it would still be very useful IMHO. Is it possible to gain sponsorship for this project or charge for the documentation, or make a commercial variant of OpenSSL which can support the open source version? Mark. ______________________________________________________________________ OpenSSL Project http://www.openssl.org User Support Mailing List openssl-users@openssl.org Automated List Manager majord...@openssl.org
