On 11/19/2012 5:19 AM, Thomas J. Hruska wrote:
On 11/13/2012 11:34 AM, Sanford Staab wrote:
I have been struggling with openssl for a few months now writing batch
scripts on windows trying to make a .net web client with a client
certificate work with 2-way ssl against an apache web server.
Do you guys just want to continue to answer questions on this alias
and not FIX the docs somewhat over time? I could go into a litany of
how much information is just missing from the docs with INCOMPLETE
everywhere. (see this link for one of the 900k+ hits on a google
search of “openssl+docs+suck” for how much hell you guys are putting
people through trying to figure out this tool)
openssl is used all over the world by tons of people (so I feel dumb
having problems here – but I know from Google I am not alone.) but it
is just unbelievable to me that the docs remain so terse and useless
for so many years.
I have sent email to this alias previously asking how I can help with
this. It seems to me there should be an openssl docs forum where
content from this eventually finds its way into the online docs
themselves.
A tool is only as good as people are able to use it.
The OpenSSL dev team consists of fairly old-school *NIX folks. It is a
low-level library and certificate generation and manipulation tool that
has gained significant notoriety for its reliability, stability, and
security.
The primary documentation is manpages. This is an outdated method of
documenting software and, as I've found, the primary source of many
complaints. In this regard, it is time to move on. I can't remember
the last time I had to fire up 'man'. I'm much more apt to just run a
Google search.
Actually, the primary format is the Perl POD format, which can be
readily "compiled" to multiple formats, including manpages (which I
prefer when coding on POSIX-like systems), HTML pages and a few others.
It would be nice if:
1. The documentation collection on openssl.org is automatically kept in
sync with the latest release tarball.
2. There are alternate areas on openssl.org holding the latest in each
of the still maintained older release series (such as 0.9.8 and 1.0.0)
and the latest development head.
3. There was an extra option in the non-POSIX build scripts for building
an indexed and cross linked folder of HTML docs, perhaps the same script
used for the automated web site updating
4. There was an extra option in the Win32/Win64 build scripts which
package the HTML pages into a properly indexed .chm file.
Enjoy
Jakob
--
Jakob Bohm, CIO, Partner, WiseMo A/S. http://www.wisemo.com
Transformervej 29, 2730 Herlev, Denmark. Direct +45 31 13 16 10
This public discussion message is non-binding and may contain errors.
WiseMo - Remote Service Management for PCs, Phones and Embedded
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users@openssl.org
Automated List Manager majord...@openssl.org
