Re: keynav man page

Hi Damien,

thanks for trying to help! However, there are large numbers of
questions to answer and large amounts of work to do before this can
usefully go anywhere.

One thing up front:

Damien Thiriet wrote on Sat, May 02, 2020 at 06:30:25PM +0200:

> Since I am not a programmer, and cannot run -current, the only way for
> me to contribute to the project is to deal with documentation

Even for that, you need to run -current, and even for working on
ports, you need sufficient programming skills to work on Makefiles.
If you lack parts of the needed skills, learn!


So, here is a plan for you:

1. This port had its last release in 2011. So on first sight,
it appears to be abandoned, i.e. no longer maintained upstream.
Please contact upstream, thank them for their work, tell them
that you use and enjoy it, ask them whether they still maintain
it, tell them that you have started to prepare improvements,
and ask them whether they might consider integrating
improvements and roll a new release if it turns out they like
your work.

2.a) If they say they have abandoned their program and won't make a
new release, or if they do not answer, your only real option
to improve the program is to take over upstream maintenance.
Ask yourself whether you want to do that, and if yes,
do take over.

2.b) If upstream is still active, instead work with upstream to
get your improvements integrated.

3. If at this point, we don't have an upstream maintainer, we
need to decide whether to keep the port around or whether to
delete it outright from the OpenBSD ports tree. Security-critical
or large programs without an upstream maintainer are usually
deleted from the ports tree. Keeping small, relatively harmless
programs around may be acceptable even when they are dead
upstream, but we don't usually try to improve programs in the
ports tree that are dead upstream. So, even if we keep the
port around, you have more or less come to a dead end with your
work until you find someone who maintains the program in general,
not just in our ports tree. Again, that can be you.

4. If you want to submit patches to the OpenBSD port, no matter
of which kind, even to just improve documentation,
you *must* run OpenBSD-current. There is no excuse.
We just don't do updates for -stable ports (except to fix
security issues, and that is only done *after* fixing them
in -current, and never by external contributors).

5. The OpenBSD port is outdated. We have 20101014, upstream
has 20110708. The very first thing to do in our ports tree
would be to decide whether the port can and should be updated
to 20110708. If yes, do it. If no, dependiing on which issues
prevent an update, try to resolve them.

6. Upstream is doing a very stupid thing. They do have a manual
page, but they fail to include it in the distribution tarball.
The manual page file is called "keynav.pod". It is neither
in mdoc(7) nor in man(7) format, but it is still a manual
page, using the third-best perlpod(1) format. Get upstream
to include that file in the distribution tarball for their
next release.

7. In the meantime, while upstream is working on the next release,
if you are in a hurry to get the manual page into the port,
make the port
* download the manual page during the "fetch" target,
see bsd.port.mk(1) for details, look for the DISTFILES
variable in there, https://man.openbsd.org/bsd.port.mk#DISTFILES
* then format it with pod2man(1) during the "post-build" phase,
see the fifth and seventh entries in TARGETS near the very
top of bsd.port.mk(1)
* then install it during the "post-install" phase
* then use "make update-plist"
* then submit a port update with a REVISION bump

8. If you want to switch the manual page from perlpod(1) to mdoc(7),
work with upstream to do so. We will not change the markup
language of the documentation in the ports tree as long as
upstream sticks to a different language.

9. If you want to improve the content of the manual page,
work with upstream to do so.


> You'll find below a keynav.mdoc file as a proposal for keynav ports.
> Any hints to improve the structure with regards to OpenBSD standards
> welcome.

From an extremely brief glance at your work, i see dozens of serious
problems with it where that work can be improved (even though it
seems to be good work). Unless you confirm that you have established
contact with upstream and they want to take patches, or until you
have taken over upstream maintenance, i am not planning to invest
the time needed to explain all those deficencies.

> I read the mdoc(7) and mandoc(8) man pages, used pod2mdoc to convert
> keynav.pod, looked at several base examples (cwm.1, cwm.5, ksh.1,
> grep.1, tmux.1) and made the converted file fit mdoc recommandations, as
> I understood them.

In principle, that's all very nice. It shows that you know how to
do research and how to work independently. I hope you persevere
with this work, because, as explained above, it is far from finished.

Yours,
Ingo