Bug 226731

Summary: Some port manual pages include version number in filename, breaking intuitive man use
Product: Ports & Packages Reporter: freebsd
Component: Individual Port(s)Assignee: freebsd-ports-bugs (Nobody) <ports-bugs>
Status: Open ---    
Severity: Affects Some People CC: cem, cy, gnome, jhale, koobs, multimedia, ports-bugs, tijl, w.schwarzenfeld
Priority: --- Keywords: needs-qa
Version: Latest   
Hardware: Any   
OS: Any   

Description freebsd 2018-03-19 16:31:25 UTC
The man command ignores trailing versioning information:

ls /usr/local/man/man1/autoconf*

$ man autoconf
No manual entry for autoconf
$ man autoconf-2
No manual entry for autoconf-2
$ man autoconf-2.69              (works)

This forces a user to do directory searches along manpath to find the proper
name to use to get the man command to work.  There are a number of man pages
with this problem, primarily in the man(1) section:

/usr/local/man$ find . -print | grep -e "[a-z]*-[-,0-9\.]*.[1-9].gz" | wc
      36      36    1009

If man fails to find a match, it would be helpful if it did something
like the following:
  Inform the user, as it does now.
  Find all man pages which match the pattern (I may have this wrong...):
  Inform the user of these results
  Do zero or more of the following:
    Ask the user to enter a new name based on the search results
    If only one result, ask the user if that's what they wanted
      Don't just deliver this unannounced, as it might not be the
      desired page, and would make the single result scroll off the
      top (it would likely be skipped by a user scanning the output
      anyway, unless hilighted in color.)

If the man command remains unchanged, then the install process for ports 
should disallow the installation of man pages with versioning information,
or at least produce warnings.  The make.conf entry "DEVELOPER=yes" should
cause this to be checked.  In terms of port checking for developers, 
warnings should also be produced for man pages with major version numbers
on the end as well, such as perl5.  A naive user might be frustrated 
when typing "man perl" if nothing appears.

Some ports such as gimp and valac provide symlinks to solve the problem;
others, like autoconf, are particular problems.

If man is not changed, bugs should be filed against at least the following
ports (I don't have all that many installed, so I have no idea what the
extent of the problem is):
  aclocal (xorg-macros?)
  gtk3    (gtk-query-immodules-3.0.1.gz)
  gimp    (gimptool-2.0.1.gz)
  vala    (vapigen-0.36.1.gz)
Comment 1 Conrad Meyer freebsd_committer 2018-03-19 16:44:28 UTC
For me, 'man autoconf<tab>' tab-completes to autoconf-2.69.  However, I can see
it as a nuisance.  I think the right thing to do is get the ports to install
unversioned man pages -- either as links or just renaming any versioned page.

The idea to automatically detect such issues in ports is not a bad one either, but it does seem rare enough that maybe we can just fix problems when people complain.  Anyway -- I don't have a ports bit so I can't really help with those parts.
Comment 2 Baptiste Daroussin freebsd_committer 2019-09-06 09:11:48 UTC
This do not belong to portmgr, but rather to individual port maintainer. which should be contacted on the case per case basis.
Comment 3 Kubilay Kocak freebsd_committer freebsd_triage 2019-09-06 09:26:11 UTC
(In reply to Baptiste Daroussin from comment #2)

What are our thoughts on adding a ports sanity check for version-suffixed man pages? That would help to highlight issues during ports QA

I don't think this bug will progress without someone dedicated to identifying all ports with this issue and opening separate bugs for them.

The least we can do at a framework level, if that's possible, is to highlight it if we can, and if it's something we agree should happen, ie: un-version-suffixed man pages
Comment 4 Walter Schwarzenfeld freebsd_triage 2019-09-06 17:03:21 UTC
CC'd maintainer:
gnome for enchant, gconf and gimp
multimedia for gstreamer1 and gstreamer
fox16 for reswrap and shutterbug
tijl for automake and autoconf
cy for fvwm
Comment 5 Walter Schwarzenfeld freebsd_triage 2019-09-06 17:18:33 UTC
(In reply to freebsd from comment #0)
> I don't have all that many installed, so I have no idea what the
> extent of the problem is

I guess mostly the Makefile or Makefile.in files.

example for autoconf:

+--- man/Makefile.in.orig       2019-09-06 16:15:02 UTC
++++ man/Makefile.in
+@@ -252,9 +252,7 @@ install-man1: $(dist_man_MANS)
+         if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
+         echo "$$d$$p"; echo "$$p"; \
+       done | \
i=> +-      sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
i=> +-            -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
=>+-      sed 'N;N;s,\n, ,g' | { \
++      { \
+       list=; while read file base inst; do \
+         if test "$$base" = "$$inst"; then list="$$list $$file"; else \
+           echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \

(needs pkg-plist change)

or automake

---- Makefile.in.orig   2018-03-11 21:21:08 UTC
+--- Makefile.in.orig   2019-09-06 16:48:14 UTC
 +++ Makefile.in
-@@ -3690,9 +3690,9 @@ doc/aclocal.1 doc/automake.1:
+@@ -2735,9 +2735,7 @@ install-man1: $(man1_MANS)
+         if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
+         echo "$$d$$p"; echo "$$p"; \
+       done | \
=> +-      sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
=> +-            -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
=> +-      sed 'N;N;s,\n, ,g' | { \
++      { \
+       list=; while read file base inst; do \
+         if test "$$base" = "$$inst"; then list="$$list $$file"; else \
+           echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
+@@ -3690,9 +3688,9 @@ doc/aclocal.1 doc/automake.1:
          && echo ".so man1/$$f-$(APIVERSION).1" > $@
  doc/aclocal-$(APIVERSION).1: $(aclocal_script) lib/Automake/Config.pm

(needs no pkg-plist change)
Comment 6 Walter Schwarzenfeld freebsd_triage 2019-09-06 17:27:00 UTC
The sed commands "transform" e.g. autoconf.1 to autoconf-2.69.1.
Comment 7 Ting-Wei Lan 2019-09-06 17:43:38 UTC
(In reply to Walter Schwarzenfeld from comment #4)
Are enchant and gstreamer relevant to this issue? You can install both enchant (1.x) and enchant2 (2.x) on the same system, so it should be expected for enchant2 to install versioned man pages. You can install both gstreamer (0.10.x) and gstreamer1 (1.x), too.

For the gimp case, I think you mean gimptool-2.0.1.gz. Since there is no unversioned gimptool command, it is expected for gimp-app to install only the versioned man page for it.

(In reply to Walter Schwarzenfeld from comment #5)
automake already installs unversioned man pages, so it needs no change for this issue.
Comment 8 Walter Schwarzenfeld freebsd_triage 2019-09-06 18:02:03 UTC
You are right with enchant and automake.

But no of the gst-* manpages work.