Re: SEE ALSO fails

[James K. Lowden]

On Sat, 30 Oct 2021 19:53:13 +0200
Ingo Schwarze <schwarze@usta.de> wrote:

> >> .Sh SEE ALSO
> >> .Xr mg 1 ,
> >> .Xr vi 1 ,
> >> .Xr editline 3edit ,
> >> .Xr el_wgets 3 ,
> >> .Xr el_wpush 3 ,
> >> .Xr el_wset 3 ,
> >> .Xr editrc 5edit
> 
> > What, I wonder, is "mg"?  
> > 
> >     $ man mg
> >     No manual entry for mg
> > 
> > Feh.  

> [dangling links] tell you that functionality is available out there
> that is related to the manual you are reading right now, but that you
> failed to install.  So hiding the dead links would be a blatant
> disservice to the reader

I think you'll acknowledge that packages frequently cross reference
each other, and can work perfectly well together even while some
optional components remain uninstalled.  

In no event did I "fail to install" anything. I installed what I
needed via the package manager.  Any failing, if that's what it was,
lies with the packaging system.  

So it comes down to this: are unmarked dangling links -- that is,
non-links -- the highest and best way to signal to the user that other
software exists related to the page in question?  

I think you'll agree that there exist better alternatives to 

> >     No manual entry for mg

as a way of informing the user of the state of the world.  

My particular beef is that I exit the man page to ... show another man
page. Which Is Not There.  Not infrequently, more than one SEE ALSO item
is missing. I don't know what's installed and what's not (based on the
text of the page) and the page provides only the name, not even so much
as the .Nd line.  Cast upon the interwebs, yes, I too can discover what
"mg" is, but it took longer than it needed to.  (From that experience,
I can tell you the NetBSD editline(3) page is for better or
worse completely silent on the subject of mg.)  

> technically extremely dirty manipulations

Are there programatic changes to man pages that you wouldn't
characterize that way?  I don't regard installed pages as sacrosanct,
especially when they mislead the user.  

I can think of half a dozen alternatives to my initial suggestion.  My
goal is to give packagers some way to avoid leading users down a
primrose path, teaching them they might as well read all their
documention on the web, because the man system is broken anyway.  

If you have any suggestion other than "it's perfect as is", I'd be
interested to hear it.  

--jkl