Bug 236237 - Port security/openssl polluted man page namespace
Summary: Port security/openssl polluted man page namespace
Status: In Progress
Alias: None
Product: Ports & Packages
Classification: Unclassified
Component: Individual Port(s) (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Bernard Spil
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2019-03-05 02:36 UTC by WHR
Modified: 2019-05-28 20:11 UTC (History)
0 users

See Also:
bugzilla: maintainer-feedback? (brnrd)


Attachments
Workaround (425 bytes, application/x-shellscript)
2019-03-05 02:36 UTC, WHR
no flags Details
svn diff for security/openssl (78.09 KB, patch)
2019-03-07 18:35 UTC, Bernard Spil
no flags Details | Diff
Script to regenerate manpage patch (975 bytes, application/x-shellscript)
2019-03-07 18:39 UTC, Bernard Spil
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description WHR 2019-03-05 02:36:52 UTC
Created attachment 202568 [details]
Workaround

I have port 'security/openssl' installed via pkg(8). One day I want to read the man page for command md5(1) from the base system; I typed:
 $ man md5
but I got dgst(1) that describing the 'openssl dgst' command. The man page file is '/usr/local/man/man1/md5.1.gz', a symbolic link to 'dgst.1.gz' in same directory. Since it is in section 1 too, I can't simply use a section number to solve this, but:
 $ man -M /usr/share/man md5

Considering it is a sub-command of the big openssl(1) command line tool, shouldn't it be named as openssl-dgst(1) and have that symbolic link named as '/usr/local/man/man1/openssl-md5.1.gz' for openssl-md5(1)?

Since there are also many other openssl man pages polluting the namespace in my system, I wrote a bash(1) script to clean this mess up for my myself. I attached this script here in case someone may interested in it.
Comment 1 Bernard Spil freebsd_committer 2019-03-07 10:56:22 UTC
Hi WHR,

I understand the sentiment, and am willing to accept a patch that solves this. The patch must not only rename the section 1 man-pages but also update all the links in the pod files to these man-pages.

For reference, I checked how this is done in 12 base. In base the links will not be generated as per upstream, but only a link with openssl- prefix is created. Though this solves the conflict on md5, all links still point to the non-prefixed man-pages.

Cheers, Bernard.
Comment 2 Bernard Spil freebsd_committer 2019-03-07 18:35:17 UTC
Created attachment 202698 [details]
svn diff for security/openssl

Tried fixing this in the port, but this becomes quite unwieldy. Maintainability is questionable. I've created a small script to change the manpages and links in the webpages so regenerating the patch should not be too difficult.
Comment 3 Bernard Spil freebsd_committer 2019-03-07 18:39:48 UTC
Created attachment 202699 [details]
Script to regenerate manpage patch

to regenerate `files/patch-openssl-cmd-prefix`:

> make do-extract
> ./rewrite-manpages.sh
> mv files orig
> make makepatch
> cd files
> cat patch-doc_* > ../files/patch-openssl-cmd-prefix
> cd ..
> rm -rf files
> mv orig files
Comment 4 Bernard Spil freebsd_committer 2019-03-07 18:42:40 UTC
Hi WHR,

On another note: The OpenSSL 1.0.2 port will be removed end of this year due to end-of-life. Have you tried security/openssl111 instead? That does not contain all the extra symlinks and does not conflict with base manpages as far as I can see.

Note: The patches/attachments are not an intent to commit to the tree.

Cheers, Bernard.
Comment 5 WHR 2019-03-08 05:24:39 UTC
Right, switching to security/openssl111 should solve this for me.
Comment 6 WHR 2019-03-11 05:46:31 UTC
I found another pollution in both security/openssl and security/openssl111. /usr/local/man/man5/config.5.gz polluted config(5) in base system /usr/share/man/man5/config.5.gz. Since OpenSSL configuration file is named 'openssl.cnf' by default, this man page should be named as openssl(5) or openssl.cnf(5).
Comment 7 Bernard Spil freebsd_committer 2019-05-28 20:11:58 UTC
Damn... Should've revisited this earlier. Today I saw the addition of config.5.

Reverted it for the update to 1.0.2s. Want to redo this in the style of OpenSSL 1.1.1. This means

 * name of manpage stays the same
 * openssl-<cmd> is a symlink to the old manpage

This to avoid POLA violations (people not being able to find the manpage as they used to) and aligns with 1.1.1. Would you be able to create a patch that does this?

Cheers, Bernard.