[openssl-users] openssl 1.1.1 manuals

[Dr. Matthias St. Pierre]

> Particularly if you don't know exactly what one is looking for...
> { There is something amiss with BIO_addr_rawaddress... it's shift right.
>   I don't see a problem in the HTML source though.. }
> 
> Sure, google will find some things, but usually it's the wrong version, and
> one has to guess what the URL for the most recent one is.
> 
> At which point, like Dennis Clarke suggests, might as well grep the POD files
> in the source code.  This is not terribly effective to find information
> about how to manipulate particular object types.
> 
> (I have started writing an index by object type for my own use, but I doubt
> I'll get very far)

The manpages are primarily what the name says: manual pages. I.e, their
primary use is the unix/linux 'man' command.

The conversion to html is an add-on to make it available via web server.
And I agree with you that static web pages are not of much help, it could
be better, more searchable.

As for grepping the POD files: There is a much simpler solution if you are using
bash on linux: Install your manual pages locally, add them to your MANPATH, and
marvel at the power of bash's tab completion.

Disclaimer: Unless you know what you are doing, you should not replace your
distribution's copy of OpenSSL by your own, but instead install it to a separate
location. For example, I have all my openssl library versions installed locally in 

  /opt/openssl-dev
  /opt/openssl-1.1.1-dev
  /opt/openssl-1.1.0-dev
  /opt/openssl-1.0.2-dev

(By configuring with --prefix=/opt/openssl-dev (etc.) and then running
'make -j 16 ; sudo make install'.)

Additionally, I have a simple script and a set of aliases 'ossl', 'ossl111'
to set the MANPATH accordingly:

  cat ~/.osslpath
  export PATH=${OSSLPATH}/bin:$ORI_PATH
  export LD_LIBRARY_PATH=${OSSLPATH}/lib:$ORI_LD_LIBRARY_PATH
  export MANPATH=${OSSLPATH}/${OSSL_MANPATH}:$ORI_MANPATH

  msp at msppc:~$ alias ossl
  alias ossl='export OSSLPATH=/opt/openssl-dev   ; OSSL_MANPATH=share/man source ~/.osslpath ; echo $OSSLPATH: $(openssl version)'

  msp at msppc:~$ alias ossl111
  alias ossl111='export OSSLPATH=/opt/openssl-1.1.1-dev ; OSSL_MANPATH=share/man source ~/.osslpath ; echo $OSSLPATH: $(openssl version)'

($ORI_PATH is initally set to $PATH in my .bashrc, and the same holds for the other $ORI_XXX)

Changing to the manual pages for the correct openssl version is now a matter of
a single command,

  msp at msppc:~$ ossl
  /opt/openssl-dev: OpenSSL 3.0.0-dev xx XXX xxxx

And voila, if your tab completion is setup correctly, help is only two <TAB>s away:
  
  msp at msppc:~$ man BIO_new <TAB> <TAB>
  BIO_new                     BIO_new_file
  BIO_new_CMS                 BIO_new_fp
  BIO_new_accept              BIO_new_mem_buf
  BIO_new_bio_pair            BIO_new_socket
  BIO_new_buffer_ssl_connect  BIO_new_ssl
  BIO_new_connect             BIO_new_ssl_connect
  BIO_new_fd


Matthias