New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Symlinks for manual page invocation #4548

Closed
mukrop opened this Issue Oct 18, 2017 · 18 comments

Comments

Projects
None yet
5 participants
@mukrop
Copy link

mukrop commented Oct 18, 2017

During an OpenSSL usability study we found out that many participants (more than a quarter) intuitively expected to find manual pages under man openssl subcommand (e.q. man openssl verify) instead of man subcommand (e.g. man verify). The experiment ran on Ubuntu 16.04.

This could be easily solved by symlinking the manual pages.
(This is already used elsewhere -- for example man git commit automatically redirects to man git-commit on Fedora.)

Although this is mostly a thing of the ports to the individual operating systems, the upstream project can probably ease the setting (as suggested by @richsalz).

@kaduk

This comment has been minimized.

Copy link
Contributor

kaduk commented Oct 18, 2017

That's not the traditional man(1) behavior -- man foo bar first displays the manual for 'foo', then when the pager exits, displays the manual for 'bar'. So this seems to be either a distro-specific issue or a user education/expectation issue.

Additionally, it's not clear that having symlinks would be helpful for all packagers -- FreeBSD, for example, uses hard links for manual pages, so having upstream OpenSSL ship symlinks would just cause extra work for the FreeBSD packagers.

So, at present, I believe that this issue is best addressed by distro packagers and not in OpenSSL proper. (But I will leave the issue open for a bit in case there is more to say.)

@mukrop

This comment has been minimized.

Copy link

mukrop commented Oct 18, 2017

I was describing a developer expectation behavior. We gave tasks to attendees of an international dev conference and over a quarter of the participants (~25/100 people) expected to find the man page under man openssl verify (the only variant used more was the correct one with things such as man openssl-verify and man openssl.verify present only marginally).

Though, this is only a suggestion. Feel free to close it, if it's not widely deployable. I opened the issue based on the recommendation from @richsalz to spark the discussion.

@mattcaswell

This comment has been minimized.

Copy link
Member

mattcaswell commented Oct 18, 2017

To expect to see something from man openssl-verify seems fairly reasonable to me (more reasonable than man verify which is what we have now).

@kaduk

This comment has been minimized.

Copy link
Contributor

kaduk commented Oct 18, 2017

I'm not opposed to having us ship something that man openssl-verify picks up on.

@levitte

This comment has been minimized.

Copy link
Member

levitte commented Oct 18, 2017

Actually, it isn't terribly difficult to add those symlinks, and they do make sense. I assume this is only for the man1 section, right?

@mattcaswell

This comment has been minimized.

Copy link
Member

mattcaswell commented Oct 18, 2017

Right.

@richsalz

This comment has been minimized.

Copy link
Contributor

richsalz commented Oct 18, 2017

Perhaps something like

openssl help verify
openssl man verify

which just exec's the right man command? Like git's git help branch does man git-branch

@levitte

This comment has been minimized.

Copy link
Member

levitte commented Oct 18, 2017

@richsalz that still requires symlinks like openssl-verify.1 to be present ;-)

@richsalz

This comment has been minimized.

Copy link
Contributor

richsalz commented Oct 18, 2017

We already do links when we install the manpages in section 3.

@levitte

This comment has been minimized.

Copy link
Member

levitte commented Oct 18, 2017

Yes?

@richsalz

This comment has been minimized.

Copy link
Contributor

richsalz commented Oct 18, 2017

So I mean, a minor update to the NAME section of almost all man1 files should do this.
See #4553. And @mukrop, please tell us how to credit your work in the commit message.

@levitte

This comment has been minimized.

Copy link
Member

levitte commented Oct 18, 2017

I obviously over-complicated things, your solution was too obvious... :-)

@richsalz

This comment has been minimized.

Copy link
Contributor

richsalz commented Oct 18, 2017

I have a simple mind. :) I'll merge once @mukrop tells us how to credit him.

@mukrop

This comment has been minimized.

Copy link

mukrop commented Oct 18, 2017

@richsalz, I'm not sure what exactly is needed. Name? Institution? Email?

@richsalz

This comment has been minimized.

Copy link
Contributor

richsalz commented Oct 18, 2017

Whatever you want to provide. It's just an acknowledgement to go into the commit message. For example, "Recommended by a study conducted by Martin Ukrop" or similar.

@mukrop

This comment has been minimized.

Copy link

mukrop commented Oct 19, 2017

"Recommended by a usability study conducted by Martin Ukrop at CRoCS, FI MU." would be nice. Thanks.

richsalz added a commit to richsalz/openssl that referenced this issue Oct 19, 2017

Additional name for all commands
Add openssl-foo as a name for the openssl "foo" command.
Recommended by a usability study conducted by Martin Ukrop at CRoCS, FI MU
Fixes: openssl#4548
(Merged from openssl#4553)
@richsalz

This comment has been minimized.

Copy link
Contributor

richsalz commented Oct 19, 2017

Argh. I forgot to update the commit commit; sorry @mukrop . But I did fix it for 1.0.2 commit.

levitte pushed a commit that referenced this issue Oct 20, 2017

Additional name for all commands
Add openssl-foo as a name for the openssl "foo" command.
Recommended by a usability study conducted by Martin Ukrop at CRoCS, FI MU
Fixes: #4548
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from #4557)
@richsalz

This comment has been minimized.

Copy link
Contributor

richsalz commented Oct 20, 2017

Merged to master, 1.1.0 and 1.0.2; thanks for the feedback.

@richsalz richsalz closed this Oct 20, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment