Online docs have broken links

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Online docs have broken links

Paul Smith
Not sure if anyone is aware or not, but many of the man pages on the
openssl.org site contain broken links.  Basically anywhere a man page
refers to a man page in a different section, the link is broken because
it uses the same section.

So for example:

  https://www.openssl.org/docs/man1.1.1/man7/ssl.html

is in section 7, but it refers to functions in section 3... however all
the links are broken because they still point to section 7.  See the
link in the second paragraph of the description to SSL_CTX_NEW, which
has this HTML linkage:

  <a href="/docs/man1.1.1/man7/SSL_CTX_new.html">SSL_CTX_new</a>

which does not exist; this should be .../man3/SSL_CTX_new.html instead.

I've found other links in the man3 section which want to refer to this
"ssl" page, and look for it in section 3 instead of section 7, also
broken.

Cheers!

Reply | Threaded
Open this post in threaded view
|

Re: Online docs have broken links

Richard Levitte - VMS Whacker-2
Good catch!  That does answer a mystery with the current HTML
producing script...

Thanks.

Cheers,
Richard

On Thu, 28 Feb 2019 20:48:02 +0100,
Paul Smith wrote:

>
> Not sure if anyone is aware or not, but many of the man pages on the
> openssl.org site contain broken links.  Basically anywhere a man page
> refers to a man page in a different section, the link is broken because
> it uses the same section.
>
> So for example:
>
>   https://www.openssl.org/docs/man1.1.1/man7/ssl.html
>
> is in section 7, but it refers to functions in section 3... however all
> the links are broken because they still point to section 7.  See the
> link in the second paragraph of the description to SSL_CTX_NEW, which
> has this HTML linkage:
>
>   <a href="/docs/man1.1.1/man7/SSL_CTX_new.html">SSL_CTX_new</a>
>
> which does not exist; this should be .../man3/SSL_CTX_new.html instead.
>
> I've found other links in the man3 section which want to refer to this
> "ssl" page, and look for it in section 3 instead of section 7, also
> broken.
>
> Cheers!
>
--
Richard Levitte         [hidden email]
OpenSSL Project         http://www.openssl.org/~levitte/
Reply | Threaded
Open this post in threaded view
|

Re: Online docs have broken links

Sam Roberts
I ran linklint on the output of `make install_html_docs`, and there
are a fair amount of refs to non-existent pages as well. Maybe its
worth adding a `test-docs` target?

Would PRs to fix the below be welcomed?

#------------------------------------------------------------
# ERROR  18 missing html files (cross referenced)
#------------------------------------------------------------
/../man1/version.html
    used in 1 file:
    /man3/CTLOG_STORE_new.html

/../man3/EVP_EncryptInit.html
    used in 1 file:
    /man3/EVP_CIPHER_meth_new.html

/../man3/OSSL_STORE_SEARCH.html
    used in 3 files:
    /man3/OSSL_STORE_expect.html
    /man3/OSSL_STORE_find.html
    /man3/OSSL_STORE_supports_search.html

/../man3/SSL_CTX_set_security_level.html
    used in 2 files:
    /man1/ciphers.html
    /man1/openssl-ciphers.html

/../man7/bio.html
    used in 4 files:
    /man3/BIO_pop.html
    /man3/BIO_push.html
    /man3/BIO_should_retry.html
    /man3/SCT_print.html

/man1/curl.html
    used in 2 files:
    /man1/openssl-tsget.html
    /man1/tsget.html

/man1/perl.html
    used in 2 files:
    /man1/openssl-ts.html
    /man1/ts.html

/man1/procmail.html
    used in 2 files:
    /man1/openssl-ts.html
    /man1/ts.html

/man3/EVP_MD_CTX_set_ctx.html
    used in 2 files:
    /man3/EVP_DigestSignInit.html
    /man3/EVP_DigestVerifyInit.html

/man3/EVP_bf.html
    used in 5 files:
    /man3/EVP_CIPHER_CTX_reset.html
    /man3/EVP_DecryptInit.html
    /man3/EVP_DecryptInit_ex.html
    /man3/EVP_EncryptInit.html
    /man3/EVP_EncryptInit_ex.html

/man3/EVP_cast5.html
    used in 5 files:
    /man3/EVP_CIPHER_CTX_reset.html
    /man3/EVP_DecryptInit.html
    /man3/EVP_DecryptInit_ex.html
    /man3/EVP_EncryptInit.html
    /man3/EVP_EncryptInit_ex.html

/man3/EVP_desx.html
    used in 5 files:
    /man3/EVP_CIPHER_CTX_reset.html
    /man3/EVP_DecryptInit.html
    /man3/EVP_DecryptInit_ex.html
    /man3/EVP_EncryptInit.html
    /man3/EVP_EncryptInit_ex.html

/man3/EVP_idea.html
    used in 5 files:
    /man3/EVP_CIPHER_CTX_reset.html
    /man3/EVP_DecryptInit.html
    /man3/EVP_DecryptInit_ex.html
    /man3/EVP_EncryptInit.html
    /man3/EVP_EncryptInit_ex.html

/man3/EVP_rc2.html
    used in 5 files:
    /man3/EVP_CIPHER_CTX_reset.html
    /man3/EVP_DecryptInit.html
    /man3/EVP_DecryptInit_ex.html
    /man3/EVP_EncryptInit.html
    /man3/EVP_EncryptInit_ex.html

/man3/EVP_rc5.html
    used in 5 files:
    /man3/EVP_CIPHER_CTX_reset.html
    /man3/EVP_DecryptInit.html
    /man3/EVP_DecryptInit_ex.html
    /man3/EVP_EncryptInit.html
    /man3/EVP_EncryptInit_ex.html

/man3/EVP_seed.html
    used in 5 files:
    /man3/EVP_CIPHER_CTX_reset.html
    /man3/EVP_DecryptInit.html
    /man3/EVP_DecryptInit_ex.html
    /man3/EVP_EncryptInit.html
    /man3/EVP_EncryptInit_ex.html

/man3/EVP_sm4.html
    used in 5 files:
    /man3/EVP_CIPHER_CTX_reset.html
    /man3/EVP_DecryptInit.html
    /man3/EVP_DecryptInit_ex.html
    /man3/EVP_EncryptInit.html
    /man3/EVP_EncryptInit_ex.html

/man3/X509_check_purpose.html
    used in 1 file:
    /man3/X509_get_extension_flags.html
Reply | Threaded
Open this post in threaded view
|

Re: Online docs have broken links

Richard Levitte - VMS Whacker-2
The problem isn't a lack of test_docs, the issue lies in how we
organised the manuals before (in an apps, a crypto and a ssl
directory), and the script that builds up these pages haven't been
updated to prefix properly per actual man section.

There's a PR that I think fixes the problem:
https://github.com/openssl/web/pull/124

Cheers,
Richard

On Fri, 01 Mar 2019 21:15:48 +0100,
Sam Roberts wrote:

>
> I ran linklint on the output of `make install_html_docs`, and there
> are a fair amount of refs to non-existent pages as well. Maybe its
> worth adding a `test-docs` target?
>
> Would PRs to fix the below be welcomed?
>
> #------------------------------------------------------------
> # ERROR  18 missing html files (cross referenced)
> #------------------------------------------------------------
> /../man1/version.html
>     used in 1 file:
>     /man3/CTLOG_STORE_new.html
>
> /../man3/EVP_EncryptInit.html
>     used in 1 file:
>     /man3/EVP_CIPHER_meth_new.html
>
> /../man3/OSSL_STORE_SEARCH.html
>     used in 3 files:
>     /man3/OSSL_STORE_expect.html
>     /man3/OSSL_STORE_find.html
>     /man3/OSSL_STORE_supports_search.html
>
> /../man3/SSL_CTX_set_security_level.html
>     used in 2 files:
>     /man1/ciphers.html
>     /man1/openssl-ciphers.html
>
> /../man7/bio.html
>     used in 4 files:
>     /man3/BIO_pop.html
>     /man3/BIO_push.html
>     /man3/BIO_should_retry.html
>     /man3/SCT_print.html
>
> /man1/curl.html
>     used in 2 files:
>     /man1/openssl-tsget.html
>     /man1/tsget.html
>
> /man1/perl.html
>     used in 2 files:
>     /man1/openssl-ts.html
>     /man1/ts.html
>
> /man1/procmail.html
>     used in 2 files:
>     /man1/openssl-ts.html
>     /man1/ts.html
>
> /man3/EVP_MD_CTX_set_ctx.html
>     used in 2 files:
>     /man3/EVP_DigestSignInit.html
>     /man3/EVP_DigestVerifyInit.html
>
> /man3/EVP_bf.html
>     used in 5 files:
>     /man3/EVP_CIPHER_CTX_reset.html
>     /man3/EVP_DecryptInit.html
>     /man3/EVP_DecryptInit_ex.html
>     /man3/EVP_EncryptInit.html
>     /man3/EVP_EncryptInit_ex.html
>
> /man3/EVP_cast5.html
>     used in 5 files:
>     /man3/EVP_CIPHER_CTX_reset.html
>     /man3/EVP_DecryptInit.html
>     /man3/EVP_DecryptInit_ex.html
>     /man3/EVP_EncryptInit.html
>     /man3/EVP_EncryptInit_ex.html
>
> /man3/EVP_desx.html
>     used in 5 files:
>     /man3/EVP_CIPHER_CTX_reset.html
>     /man3/EVP_DecryptInit.html
>     /man3/EVP_DecryptInit_ex.html
>     /man3/EVP_EncryptInit.html
>     /man3/EVP_EncryptInit_ex.html
>
> /man3/EVP_idea.html
>     used in 5 files:
>     /man3/EVP_CIPHER_CTX_reset.html
>     /man3/EVP_DecryptInit.html
>     /man3/EVP_DecryptInit_ex.html
>     /man3/EVP_EncryptInit.html
>     /man3/EVP_EncryptInit_ex.html
>
> /man3/EVP_rc2.html
>     used in 5 files:
>     /man3/EVP_CIPHER_CTX_reset.html
>     /man3/EVP_DecryptInit.html
>     /man3/EVP_DecryptInit_ex.html
>     /man3/EVP_EncryptInit.html
>     /man3/EVP_EncryptInit_ex.html
>
> /man3/EVP_rc5.html
>     used in 5 files:
>     /man3/EVP_CIPHER_CTX_reset.html
>     /man3/EVP_DecryptInit.html
>     /man3/EVP_DecryptInit_ex.html
>     /man3/EVP_EncryptInit.html
>     /man3/EVP_EncryptInit_ex.html
>
> /man3/EVP_seed.html
>     used in 5 files:
>     /man3/EVP_CIPHER_CTX_reset.html
>     /man3/EVP_DecryptInit.html
>     /man3/EVP_DecryptInit_ex.html
>     /man3/EVP_EncryptInit.html
>     /man3/EVP_EncryptInit_ex.html
>
> /man3/EVP_sm4.html
>     used in 5 files:
>     /man3/EVP_CIPHER_CTX_reset.html
>     /man3/EVP_DecryptInit.html
>     /man3/EVP_DecryptInit_ex.html
>     /man3/EVP_EncryptInit.html
>     /man3/EVP_EncryptInit_ex.html
>
> /man3/X509_check_purpose.html
>     used in 1 file:
>     /man3/X509_get_extension_flags.html
>
--
Richard Levitte         [hidden email]
OpenSSL Project         http://www.openssl.org/~levitte/
Reply | Threaded
Open this post in threaded view
|

Re: Online docs have broken links

Paul Smith
On Fri, 2019-03-01 at 23:58 +0100, Richard Levitte wrote:
> The problem isn't a lack of test_docs, the issue lies in how we
> organised the manuals before (in an apps, a crypto and a ssl
> directory), and the script that builds up these pages haven't been
> updated to prefix properly per actual man section.
>
> There's a PR that I think fixes the problem:
> https://github.com/openssl/web/pull/124

Thanks for looking into this issue.

I had another request: can you adjust the title of the pages?
Currently the titles look like this:

  <title>
  /docs/man1.1.1/man3/SSL_accept.html
  </title>

This can be frustrating when I have a bunch of SSL docs open in tabs in
my browser; the tab titles are all truncated to just "/docs/man..." or
whatever will fit.

I would prefer the title to be something like:

  <title>
  SSL_accept(3)
  </title>

If you would like to keep the version in the title maybe it could be
added after the name, something like:

  <title>
  SSL_accept(3) [1.1.1]
  </title>

or similar.

Cheers!