snap: Add man pages.

[fnordahl]

The upstream OVS and OVN projeccts provide detailed documentation in their manpages. It would be a shame to deprieve the user of this documentation.

There have been efforts to bring man page support to the snap infrastructure [0][1], but it has unfortunately not come to fruition. We need to bring the required components ourself.

Example to view the OVN Architecture documentation:

microovn.man ovn-architecture

0: https://forum.snapcraft.io/t/support-for-man-pages/2299
1: canonical/snapd#8079
Signed-off-by: Frode Nordahl [email protected]

[pmatulis]

I'm not 100% on what the intended user experience is here.

1. Will those listed upstream man page links remain?
2. Will the user have access to those pages via the man command?
3. Is there just microovn.man ovn-architecture as a MicroOVN man page?

[fnordahl]

Thank you for taking a time to look @pmatulis, much appreciated!

I'm not 100% on what the intended user experience is here.

In short:

microovn.man ovn-nbctl

You could replace the argument with any other OVS/OVN command.

1. Will those listed upstream man page links remain?

Yes, they point to the web version of Ubuntu's man pages which has a pretty long lifetime. We need to figure out some automatic way of how to link to the correct Ubuntu version corresponding with what is in the snap for any given branch. Will ponder a bit about how to do that.

2. Will the user have access to those pages via the `man` command?

Unfortunately not. In the commit message there are links to non-concluded discussions for how this could be provided by the snapd/snapcraft infrastructure. Until we get that we need to provide our own way.

Providing microovn.man <insert any OVS or OVN man-page> can be a useful compromise.

3. Is there just `microovn.man ovn-architecture` as a MicroOVN man page?

No, all OVS and OVN manpages are included in the snap as of this proposal.

[pmatulis]

microovn.man ovn-nbctl
You could replace the argument with any other OVS/OVN command.

In another discussion there was talk of a microovn alias. Would that affect any of this?

1. Will those listed upstream man page links remain?
   Yes, they point to the web version of Ubuntu's man pages

So we would be providing our users with help on the command line as well as via the documentation. Both will provide the same information?

Providing microovn.man can be a useful compromise.

Traditional man includes argument auto-completion for most shells. I imagine that this will not be the case with your proposed implementation? Is there a concern that users will be unable to find the exact command name?

Will there be any MicroOVN-specific commands involved in any of this?